Next.js如何通过配置文件而非文件夹结构定义页面与API路由

Next.js 默认的文件系统路由没有提供原生的集中配置入口，但你完全可以用极低的成本实现和 react-router 等常规路由库一致的单文件配置体验，不需要改动框架核心能力。

实现思路 #

核心逻辑是用单独的配置文件统一定义所有路由，通过脚本自动生成Next.js要求的文件路由结构，你全程不需要手动维护app/或者pages/目录下的路由文件，所有路由规则都在独立配置文件里维护，同时完全保留Next.js原生的路由预加载、代码分割、RSC、缓存等所有能力。

具体实现步骤 #

1. 新建统一路由配置文件 #

在项目根目录新建routes.config.js，所有页面路由、API路由都在这里定义，支持动态参数、嵌套路由，你可以自己扩展权限标识、页面标题等自定义字段：

// routes.config.js
export const pageRoutes = [
  {
    path: '/',
    component: 'home', // 对应你实际存放页面组件的路径，比如 src/page-entries/home.jsx
  },
  {
    path: '/blog/:slug',
    component: 'blog/detail',
  },
  {
    path: '/user/:userId/settings',
    component: 'user/settings',
    requiredAuth: true, // 自定义字段，做路由拦截用
  }
]

export const apiRoutes = [
  {
    path: '/api/user/:userId',
    handler: 'user/getUser', // 对应实际存放API处理函数的路径，比如 src/api-entries/user/getUser.js
  },
  {
    path: '/api/post/publish',
    handler: 'post/publish',
    method: ['POST']
  }
]

2. 写自动生成路由的脚本 #

在根目录新建gen-routes.js，作用是把你写的路由配置，自动转换成Next.js识别的文件路由结构，动态路由会自动转成[param]的命名格式：

const fs = require('fs')
const path = require('path')
const { pageRoutes, apiRoutes } = require('./routes.config.js')

// 把配置里的 :param 格式转成Next.js要求的 [param] 格式
function formatRoutePath(routePath) {
  return routePath.replace(/:([^/]+)/g, '[$1]')
}

// 生成页面路由
pageRoutes.forEach(route => {
  const nextRoutePath = formatRoutePath(route.path)
  const targetDir = path.join(__dirname, 'app', nextRoutePath)
  fs.mkdirSync(targetDir, { recursive: true })
  // 写入page.js，直接导入你实际写的页面组件
  const fileContent = `export { default } from '@/page-entries/${route.component}'\n`
  fs.writeFileSync(path.join(targetDir, 'page.js'), fileContent)
})

// 生成API路由
apiRoutes.forEach(route => {
  const nextRoutePath = formatRoutePath(route.path)
  const targetDir = path.join(__dirname, 'app', nextRoutePath)
  fs.mkdirSync(targetDir, { recursive: true })
  // 写入route.js，导入你实际写的API处理函数
  const fileContent = `
export { GET, POST, PUT, DELETE } from '@/api-entries/${route.handler}'
`
  fs.writeFileSync(path.join(targetDir, 'route.js'), fileContent)
})

3. 配置脚本自动执行 #

修改package.json里的脚本命令，让路由生成逻辑在开发、构建前自动跑，不用手动执行：

{
  "scripts": {
    "predev": "node gen-routes.js",
    "prebuild": "node gen-routes.js",
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

其他可选方案（不推荐） #

如果你不想生成实体文件，也可以用全捕获路由做兜底：在app目录下新建[[...path]]/page.js和[[...path]]/route.js，在内部获取当前路径后匹配你的路由配置表，手动渲染对应组件/转发API请求。但这种方案会丢失Next.js原生的路由级代码分割、静态生成、增量静态再生等性能优化，只适合小型测试项目用。

注意事项 #

• 自动生成的app目录下的路由文件可以直接加入.gitignore，不需要提交到代码仓库，团队成员拉代码后跑npm run dev就会自动生成。注意写清理逻辑的时候不要覆盖你手动写的layout.js、loading.js、error.js等根级公共文件。
• 路由参数的获取和原生写法完全一致：页面组件用useParams()、useSearchParams()拿参数，API处理函数从请求对象里取参数即可，没有额外学习成本。
• 你可以在路由配置里加任意自定义字段，统一做权限拦截、面包屑生成、页面标题设置等逻辑，比散落在文件夹结构里的路由维护成本低很多。

内容的提问来源于stack exchange，提问作者Kaki Master Of Time