为什么你的 React 项目越改越乱？这 3 个配置细节藏着答案

初始化项目时的每一个配置选择，其实都藏着对项目未来的预判。就像用vite而非create-react-app，选useContext+useReducer而非 Redux，这些看似微小的决定，会在项目迭代中逐渐显现出架构设计的价值。今天就从路由配置和状态管理的底层逻辑说起，聊聊这套配置为什么值得这么做。

一、路由分层配置：为什么要把<BrowserRouter>放在main.jsx？

刚学 React Router 时，我总习惯把<BrowserRouter>和<Routes>写在同一个文件里，觉得这样直观。直到维护一个 10 万行代码的项目时才发现，这种 "一锅烩" 的写法会让路由重构变得异常痛苦。现在这套分层配置，其实是踩过无数坑后的最优解。

1. 职责分离

先看代码结构：

// main.jsx - 框架层
createRoot(document.getElementById('root')).render(
  <BrowserRouter>
    <App/>
  </BrowserRouter>
)

// App.jsx - 应用层
function App() {
  return (
    <Suspense fallback={<Loading />}>
      <Routes>
        <Route path='/' element={<Home />} />
        <Route path='/users/:id/repos' element={<RepoList />}/>
        {/* 其他路由 */}
      </Routes>
    </Suspense>
  )
}

这种拆分的核心是把 "路由能力" 和 "路由规则" 彻底分开：

• <BrowserRouter>的本质是 "路由环境提供者"，它负责：

  • 监听浏览器地址栏变化（popstate事件）
  • 管理路由历史记录（history对象）
  • 提供路由上下文（让子组件能访问useParams、useNavigate等钩子）
    这些都是框架级的基础能力，和具体业务无关。

• <Routes>和<Route>则是 "路由规则执行者"，它们负责：

  • 匹配当前 URL 和路由路径
  • 渲染对应的组件
  • 处理嵌套路由和 404 页面
    这些是应用级的业务逻辑，会随着项目迭代频繁变更。

想象一下，如果把它们写在一起，当需要切换路由模式（比如从BrowserRouter换成HashRouter），或者给路由加全局守卫时，就不得不改动包含业务路由的文件 ------ 这就像换灯泡时要拆整个天花板，完全违背了 "开闭原则"。

2. 性能优化

React 的渲染机制是 "父组件更新会触发子组件更新"。如果把<BrowserRouter>和<Routes>放一起，当路由规则变化时（比如新增一个路由），整个路由环境会重新初始化，导致：

• 路由历史记录被重置（用户无法回退到之前的页面）
• 所有路由组件强制卸载再挂载（丢失组件内部状态）
• 性能损耗（特别是有路由级代码分割时）

分层配置后，<BrowserRouter>作为顶层组件，只会在应用初始化时渲染一次，后续路由规则的变化不会影响它 ------ 就像房子的地基不会因为换家具而重建。

3. 测试便捷

写单元测试时，最头疼的就是组件依赖全局环境。比如测试RepoList组件时，如果它依赖<BrowserRouter>，就必须在测试文件里套一层路由，否则useParams会报错。

现在这种配置下，测试App组件时可以用MemoryRouter（React Router 提供的内存路由，不依赖浏览器环境）：

// App.test.jsx
test('渲染404页面', () => {
  render(
    <MemoryRouter initialEntries={['/invalid-path']}>
      <App />
    </MemoryRouter>
  )
  expect(screen.getByText('404')).toBeInTheDocument()
})

而测试RepoList这类页面组件时，甚至不需要完整路由，只需模拟useParams返回的参数：

// RepoList.test.jsx
jest.mock('react-router-dom', () => ({
  ...jest.requireActual('react-router-dom'),
  useParams: () => ({ id: 'test-user' })
}))

test('加载用户仓库列表', () => {
  render(<RepoList />)
  // 直接测试组件逻辑，无需关心路由环境
})

这种 "环境隔离" 的测试方式，能让单测速度提升 30% 以上，尤其在大型项目中效果明显。

4. 扩展性

当项目增长到一定规模，你可能会遇到这些需求：

• 实现路由级权限控制（比如未登录用户跳转登录页）
• 加入路由切换动画（需要监听路由变化）
• 支持微前端（不同子应用共享路由）

这套分层配置能轻松应对这些场景。比如加一个全局路由守卫：

// main.jsx
function AuthRouter({ children }) {
  const { isLogin } = useAuth()
  const location = useLocation()

  useEffect(() => {
    if (!isLogin && location.pathname !== '/login') {
      navigate('/login')
    }
  }, [isLogin, location.pathname])

  return children
}

createRoot(document.getElementById('root')).render(
  <BrowserRouter>
    <AuthRouter>
      <App />
    </AuthRouter>
  </BrowserRouter>
)

由于<BrowserRouter>在最外层，我们可以在它和<App>之间插入任意中间件，而不需要修改业务路由配置。这种 "插件式" 扩展，比修改App.jsx里的<Routes>要优雅得多。

二、全局状态管理：为什么GlobalProvider要包裹在路由外层？

在main.jsx里，GlobalProvider包裹着<BrowserRouter>，这种看似简单的顺序，其实决定了状态管理的 "生命周期"：

// main.jsx
createRoot(document.getElementById('root')).render(
  <GlobalProvider>
    <BrowserRouter>
      <App/>
    </BrowserRouter>
  </GlobalProvider>
)

这和传统把状态放在App组件里的写法有本质区别，我们来拆解这种设计的深层逻辑。

1. 状态生命周期

传统写法中，如果把状态放在App组件里，当路由切换导致App重新渲染时（比如App里有依赖路由的状态），全局状态会被重置。这就会出现：

• 用户在RepoList页筛选了条件，切换到RepoDetail再回来，筛选条件丢失
• 全局加载状态（loading）在路由跳转时被意外重置

而GlobalProvider放在最外层后，状态的生命周期和整个应用一致：

• 从应用启动到关闭，状态始终存在
• 路由切换、组件卸载都不会影响状态的持久性
• 即使用户刷新页面（配合localStorage持久化），关键状态也能恢复

这对需要 "跨页面保持" 的场景至关重要，比如用户登录状态、主题设置、全局过滤器等。

2. 依赖解耦

假设我们要在RepoDetail页显示 "当前用户所有仓库数量"，这个数据来自全局状态。如果状态依赖路由，就会形成 "路由→状态→组件" 的循环依赖：

• 路由变化需要更新状态
• 状态更新又会触发路由组件重新渲染

而现在的结构是 "状态→路由→组件" 的单向依赖：

• 状态不依赖路由，可以独立更新
• 路由组件通过useContext消费状态，不关心状态从哪来
• 状态变化时，只有使用该状态的组件会更新，路由本身不受影响

这种解耦在项目变大后会非常明显。比如后来需要在Home页也显示仓库数量，只需在Home组件里调用useContext，无需修改路由或状态逻辑。

3. 数据预加载

现代应用常需要 "首屏渲染前加载关键数据"，比如用户权限、全局配置。GlobalProvider在最外层，让这种预加载变得可能：

// GlobalContext.jsx
export const GlobalProvider = ({ children }) => {
  const [state, dispatch] = useReducer(repoReducer, initialState)
  const [isReady, setIsReady] = useState(false)

  // 应用启动时预加载数据
  useEffect(() => {
    const preload = async () => {
      dispatch({ type: 'FETCH_START' })
      try {
        const userInfo = await getCurrentUser() // 获取当前用户信息
        dispatch({ type: 'INIT_USER', payload: userInfo })
        setIsReady(true)
      } catch (error) {
        dispatch({ type: 'FETCH_ERROR', payload: error.message })
        setIsReady(true)
      }
    }
    preload()
  }, [])

  if (!isReady) {
    return <SplashScreen /> // 显示启动屏
  }

  return (
    <GlobalContext.Provider value={{ state, dispatch }}>
      {children}
    </GlobalContext.Provider>
  )
}

由于GlobalProvider在路由外层，它可以在路由渲染前就完成数据加载。用户看到的第一个画面不是 "空白 + 加载中"，而是准备充分的首屏内容 ------ 这种体验优化，在传统状态管理写法中很难实现。

4. 可扩展性

当项目从 "小而美" 成长为 "大而全"，你可能会发现useContext+useReducer不够用了（比如需要中间件、状态持久化等高级功能）。这时这套架构的优势就体现出来了：

// 从useContext+useReducer迁移到Redux
import { Provider } from 'react-redux'
import store from './store'

// main.jsx
createRoot(document.getElementById('root')).render(
  <Provider store={store}> {/* 替换GlobalProvider */}
    <BrowserRouter>
      <App/>
    </BrowserRouter>
  </Provider>
)

组件里的useContext调用只需换成useSelector和useDispatch，业务逻辑几乎不用改。这种 "平滑迁移" 的能力，比一开始就用 Redux 但后期想简化要重要得多 ------ 毕竟不是所有项目都需要重量级状态管理。

三、自定义 Hooks：为什么要把 API 调用封装成useRepos？

在RepoList组件里，我们没有直接写useContext和 API 调用，而是用了一个自定义 HookuseRepos：

// RepoList.jsx
const RepoList = () => {
  const { id } = useParams()
  const { repos, loading, error } = useRepos(id)
  // 只关心渲染逻辑
}

这种封装看似多了一层，却解决了三个核心问题：

1. 避免重复代码

如果每个组件都自己写 API 调用逻辑，会出现大量重复代码：

// 未封装时的重复代码
const RepoList = () => {
  const { state, dispatch } = useContext(GlobalContext)
  useEffect(() => {
    dispatch({ type: 'FETCH_START' })
    getRepos(id).then(res => {
      dispatch({ type: 'FETCH_SUCCESS', payload: res.data })
    }).catch(err => {
      dispatch({ type: 'FETCH_ERROR', payload: err.message })
    })
  }, [id])
}

// RepoDetail里还要再来一套类似的
const RepoDetail = () => {
  const { state, dispatch } = useContext(GlobalContext)
  useEffect(() => {
    // 几乎一样的逻辑，只是API不同
  }, [repoId])
}

而useRepos把这些逻辑抽离后，不仅减少了代码量，更重要的是统一了数据获取的逻辑 。当需要修改错误处理方式（比如加一个全局错误提示），只需改useRepos这一个地方，不用逐个组件修改。

2. 组件只做渲染，Hook 只做数据

RepoList组件的核心职责是 "根据数据渲染 UI"，而 "如何获取数据" 属于另一个维度的逻辑。把它们混在一起，会导致：

• 组件代码臃肿，动辄几百行
• 想改 UI 时要小心翼翼避开数据逻辑
• 测试组件时要同时处理 API 调用的 mock

useRepos通过 "自定义 Hook" 这种形式，实现了数据逻辑和 UI 逻辑的分离：

• useRepos负责：调用 API、更新状态、处理加载和错误
• RepoList负责：接收数据、条件渲染、处理用户交互

这种分离让代码更符合 "单一职责原则"，也让新手更容易接手 ------ 想改 UI 就看组件，想改数据逻辑就看 Hook。

3. 跨组件共享数据逻辑

假设项目后期加了一个 "仓库搜索" 功能，需要调用同样的getReposAPI，只是参数多了个keyword。这时useRepos可以轻松扩展：

// useRepos.js 扩展后
export const useRepos = (id, keyword = '') => {
  const { state, dispatch } = useContext(GlobalContext)
  useEffect(() => {
    dispatch({ type: 'FETCH_START' })
    (async () => {
      try {
        const res = await getRepos(id, keyword) // 新增参数
        dispatch({ type: 'FETCH_SUCCESS', payload: res.data })
      } catch (error) {
        dispatch({ type: 'FETCH_ERROR', payload: error.message })
      }
    })()
  }, [id, keyword]) // 依赖新增参数
  return state
}

无论是RepoList还是新的RepoSearch组件，都能复用这套逻辑。这种复用比复制粘贴要可靠得多，因为逻辑变更时所有使用处都会同步更新。

架构设计的本质是 "预判未来"

这套配置从表面看是 "代码位置的调整"，但深层是对项目生命周期的预判：

• 路由分层配置，预判了 "路由规则会频繁变更，但路由环境相对稳定"
• GlobalProvider在外层，预判了 "状态需要跨越路由存在"
• 自定义 Hook 封装，预判了 "数据逻辑会在多组件复用"

这些预判不一定在项目初期就体现价值，但当项目从几个页面增长到几十个页面，从一个开发者变成一个团队时，这种 "提前设计" 会显著降低维护成本。

前端架构没有银弹，最好的方案永远是 "适合当前阶段，且能平滑过渡到下一阶段" 的方案。这套基于useContext+useReducer的配置，或许就是中小型 React 项目的最优解 ------ 足够简单，又足够灵活。