指南
示例
API
贡献
指南
示例
API
贡献

常见问题

这里收集了使用 @feoe/fs-router 时最常遇到的问题和解决方案。

安装和配置问题

Q: 安装后插件不工作怎么办？

A: 请检查以下几点：

  1. 确认插件配置正确

    1// vite.config.ts
2import { FileBasedRouterVite } from '@feoe/fs-router/vite'
3
4export default defineConfig({
5  plugins: [
6    react(),
7    FileBasedRouterVite({
8      routesDirectory: 'src/routes',
9      generatedRoutesPath: 'src/routes.tsx'
10    })
11  ]
12})

  2. 检查路由目录是否存在

    1# 确保路由目录存在
2mkdir -p src/routes

  3. 重启开发服务器

    1npm run dev
2# 或
3yarn dev

Q: TypeScript 报错找不到模块？

A: 这通常是路径配置问题：

  1. 检查 tsconfig.json 配置

    1{
2  "compilerOptions": {
3    "baseUrl": ".",
4    "paths": {
5      "@/*": ["./src/*"],
6      "@/routes": ["./src/routes.tsx"]
7    }
8  },
9  "include": [
10    "src/**/*",
11    "src/routes.tsx"
12  ]
13}

  2. 确认生成的路由文件存在

    1# 检查文件是否生成
2ls -la src/routes.tsx

  3. 重启 TypeScript 服务

    • VS Code: Ctrl+Shift+P → "TypeScript: Restart TS Server"

Q: 构建时出现路径错误？

A: 检查相对路径配置：

  1. 使用绝对路径或别名

    1// ❌ 避免使用相对路径
2import { routes } from './routes'
3
4// ✅ 使用别名
5import { routes } from '@/routes'

  2. 配置构建工具别名

    1// vite.config.ts
2export default defineConfig({
3  resolve: {
4    alias: {
5      '@': path.resolve(__dirname, './src')
6    }
7  }
8})

路由相关问题

Q: 路由不生效，页面显示 404？

A: 检查以下几个方面：

  1. 文件命名是否正确

    ✅ 正确命名 src/routes/page.tsx # 首页 src/routes/about/page.tsx # 关于页面 ❌ 错误命名 src/routes/index.tsx # 应该是 page.tsx src/routes/about.tsx # 应该在 about/page.tsx

  2. 组件导出是否正确

    1// ✅ 正确导出
2export default function HomePage() {
3  return <div>首页</div>
4}
5
6// ❌ 错误导出
7export function HomePage() {  // 缺少 default
8  return <div>首页</div>
9}

  3. 路由配置是否正确使用

    1// src/main.tsx
2import { createBrowserRouter, RouterProvider } from 'react-router-dom'
3import { routes } from '@/routes'
4
5const router = createBrowserRouter(routes)
6
7ReactDOM.createRoot(document.getElementById('root')!).render(
8  <RouterProvider router={router} />
9)

Q: 动态路由参数获取不到？

A: 检查动态路由配置：

  1. 文件命名格式

    ✅ 正确格式 src/routes/user/[id]/page.tsx # 单个参数 src/routes/blog/[...slug]/page.tsx # 捕获所有参数 ❌ 错误格式 src/routes/user/{id}/page.tsx # 应该用方括号 src/routes/user/id/page.tsx # 缺少方括号

  2. 参数获取方式

    1import { useParams } from 'react-router-dom'
2
3export default function UserPage() {
4  const { id } = useParams()  // 参数名对应文件名
5  
6  return <div>用户 ID: {id}</div>
7}

Q: 嵌套路由布局不显示？

A: 检查布局组件配置：

  1. 确保使用 Outlet

    1// src/routes/layout.tsx
2import { Outlet } from 'react-router-dom'
3
4export default function RootLayout() {
5  return (
6    <div>
7      <header>导航</header>
8      <main>
9        <Outlet />  {/* 必须包含 Outlet */}
10      </main>
11    </div>
12  )
13}

  2. 检查嵌套结构

    src/routes/ ├── layout.tsx # 根布局 ├── page.tsx # 首页 └── user/ ├── layout.tsx # 用户布局 ├── page.tsx # 用户首页 └── [id]/ └── page.tsx # 用户详情

开发环境问题

Q: 热更新不工作？

A: 检查开发环境配置：

  1. 确认插件配置

    1FileBasedRouterVite({
2  routesDirectory: 'src/routes',
3  generatedRoutesPath: 'src/routes.tsx',
4  watch: true  // 确保启用监听
5})

  2. 检查文件监听

    1# 检查文件是否被正确监听
2# 修改路由文件后应该看到重新生成的日志

  3. 重启开发服务器

    1# 有时需要重启服务器
2npm run dev

Q: 开发时路由文件频繁重新生成？

A: 这可能是文件监听配置问题：

  1. 配置忽略文件

    1FileBasedRouterVite({
2  routesDirectory: 'src/routes',
3  generatedRoutesPath: 'src/routes.tsx',
4  watchOptions: {
5    ignored: ['**/*.test.tsx', '**/*.spec.tsx', '**/node_modules/**']
6  }
7})

  2. 调整防抖延迟

    1FileBasedRouterVite({
2  watchOptions: {
3    debounceMs: 300  // 增加防抖延迟
4  }
5})

构建和部署问题

Q: 生产构建失败？

A: 检查构建配置：

  1. 确认所有依赖已安装

    1npm install
2# 或
3yarn install

  2. 检查 TypeScript 错误

    1npx tsc --noEmit

  3. 检查导入路径

    1// 确保所有导入路径正确
2import { routes } from '@/routes'  // 使用配置的别名

Q: 部署后路由不工作？

A: 这通常是服务器配置问题：

  1. 配置服务器重写规则

    1# Nginx 配置
2location / {
3  try_files $uri $uri/ /index.html;
4}
    1# Apache 配置 (.htaccess)
2RewriteEngine On
3RewriteCond %{REQUEST_FILENAME} !-f
4RewriteCond %{REQUEST_FILENAME} !-d
5RewriteRule . /index.html [L]

  2. 使用 HashRouter（临时方案）

    1// 如果无法配置服务器，可以临时使用 HashRouter
2import { createHashRouter } from 'react-router-dom'
3
4const router = createHashRouter(routes)

性能问题

Q: 首次加载很慢？

A: 优化加载性能：

  1. 启用代码分割

    1FileBasedRouterVite({
2  typeGenerateOptions: {
3    routesTypeFile: 'src/routes-type.ts',
4    generateRouteParams: true,
5    generateLoaderTypes: true,
6    routesDirectories: []
7  }
8})

  2. 预加载关键路由

    1// 预加载重要页面
2import('./routes/home/page')
3import('./routes/about/page')

Q: 路由切换卡顿？

A: 优化路由切换：

  1. 使用 Suspense 和 Loading

    1import { Suspense } from 'react'
2
3function App() {
4  return (
5    <Suspense fallback={<div>加载中...</div>}>
6      <RouterProvider router={router} />
7    </Suspense>
8  )
9}

  2. 优化组件渲染

    1import { memo } from 'react'
2
3const ExpensiveComponent = memo(function ExpensiveComponent() {
4  // 复杂组件逻辑
5})

集成问题

Q: 与状态管理库冲突？

A: 正确集成状态管理：

  1. 在 loader 中更新状态

    1// 使用 Zustand
2export async function loader({ params }) {
3  const user = await fetchUser(params.id)
4  useUserStore.getState().setUser(user)
5  return { user }
6}

  2. 避免在组件中直接调用 API

    1// ❌ 避免
2useEffect(() => {
3  fetchUser(id).then(setUser)
4}, [id])
5
6// ✅ 推荐 - 使用 loader
7const { user } = useLoaderData()

Q: 与 UI 库样式冲突？

A: 解决样式冲突：

  1. 使用 CSS Modules 或 Styled Components

    1import styles from './page.module.css'
2
3export default function Page() {
4  return <div className={styles.container}>内容</div>
5}

  2. 配置 CSS 作用域

    1// vite.config.ts
2export default defineConfig({
3  css: {
4    modules: {
5      scopeBehaviour: 'local'
6    }
7  }
8})

调试技巧

启用调试模式

1// 开发环境启用详细日志
2FileBasedRouterVite({
3  development: {
4    logGeneration: true,
5    showDebugInfo: true
6  }
7})

检查生成的路由

1// 在控制台查看生成的路由
2console.log('生成的路由:', routes)

使用 React Developer Tools

安装 React Developer Tools 浏览器扩展，可以查看路由状态和组件树。

获取帮助

如果以上解决方案都无法解决您的问题：

  1. 查看 GitHub Issues

    • 搜索相似问题
    • 查看已知问题列表

  2. 提交 Bug 报告

    • 提供详细的错误信息
    • 包含最小复现示例
    • 说明环境信息

  3. 社区讨论

    • 参与社区讨论
    • 分享使用经验
    • 帮助其他用户
页面导航