Next.js 的 API 路由可以说是整个框架里最实用的特性之一业务代码写在文件里文件放在对应的目录下一个接口就自动暴露出来了不用像传统后端那样去注册路由、配置控制器。但正因为它“按文件系统约定路由”文件命名就成了接口能不能正常跑起来的命门。我自己接过不少 Next.js 项目一大半的 404 和 500 都出在命名上——有的是把index.ts当普通文件用有的是动态路由的[id]写成了[id].ts还有的是route.ts和page.tsx放进了同一个目录导致冲突。这篇就把 API 路由文件命名的规则、优先级、冲突场景和最佳实践一次性讲透适合刚接触 Next.js 的前端开发者也能帮已经上手一段时间的同学把容易踩的坑补齐。1. API 路由文件命名到底在约定什么1.1 文件名即 URL目录映射是根逻辑Next.js 的 API 路由和页面路由共用同一套文件系统路由机制核心规则只有一条文件在磁盘上的位置决定了它对外暴露的 URL 路径。以 Pages Router 为例pages/api目录就是所有 API 接口的根pages/api/user.ts对应GET /api/userpages/api/user/profile.ts对应GET /api/user/profile。换句话说你不需要在任何配置文件里声明路由文件系统本身就是路由表。这个设计最初是从 PHP、Ruby on Rails 那套“约定优于配置”的思路延续下来的。它的好处非常直接新加一个接口只需要新增一个文件删掉一个接口直接删文件代码评审时通过文件名就能看出接口的层级结构。对个人开发者或者小团队来说这种映射关系几乎零学习成本对大型项目来说只要约定好命名规范接口的组织形式也不会乱。但“约定优于配置”的另一面是——你只能在约定范围内发挥。文件命名的任何偏差都会直接改变 URL甚至导致路由不生效。比如你把pages/api/users.ts改名为pages/api/userInfo.ts那么/api/userInfo可用而/api/users会立即变成 404这个行为在开发环境热更新下几乎是瞬间生效的不会有任何迁移提示。1.2 两类 Router 的命名差异Pages 与 AppNext.js 目前存在两套路由体系。Pages Router 是经典方案API 文件后缀为.ts/.js文件名直接等于路由段App Router 是 Next.js 13 之后推广的新方案API 文件名固定为route.ts真正的路径靠所在文件夹名决定。两套体系对“命名”这个概念的理解完全不同维度Pages RouterApp RouterAPI 文件根目录pages/api/app/api/文件名规则文件名 路由路径文件名固定为route.ts路径来源文件路径文件夹路径动态段表示[param].ts文件夹名[param]/route.ts可选动态段[[...param]].ts文件夹名[[...param]]/route.ts这两套体系在命名上最大的坑是很多从 Pages Router 迁移到 App Router 的开发者习惯性把route.ts命名为user.ts或users.ts结果接口直接不注册。App Router 的 API 路由只认route这一个文件名其他任何文件名包括api.ts、handler.ts都会被当作普通文件忽略掉。这个后面单独用一整节展开说。2. Pages Router 的完整命名规则拆解2.1 基础命名与index.ts的特殊身份Pages Router 里最简单的情况是静态命名pages/api/hello.ts对应/api/hello方法不限GET、POST、PUT、DELETE 都可以在这个文件里通过export default导出一个 handler。一个只处理 GET 请求的接口长这样// pages/api/hello.ts import type { NextApiRequest, NextApiResponse } from next; export default function handler(req: NextApiRequest, res: NextApiResponse) { res.status(200).json({ message: Hello }); }这里要特别注意index.ts。pages/api/index.ts对应的 URL 是/api不是/api/index。很多新手把index.ts当成普通的“首页”概念来用但其实它的语义是“这个目录的默认路由”。同理pages/api/user/index.ts对应/api/user而pages/api/user.ts也对应/api/user——这两个文件如果同时存在Next.js 会启动时直接报错告诉你路由冲突因为它们在 URL 层面完全相同。实际使用中我建议尽量用index.ts表达“资源的集合根路径”比如pages/api/users/index.ts处理GET /api/users列表和POST /api/users创建再用pages/api/users/[id].ts处理/api/users/1这类单资源操作。这样 URL 语义最干净文件夹结构也能直接映射成 RESTful 的资源层级。2.2 动态路由[param].ts的命名与取值动态路由是 API 开发里最常用的命名模式。[param]用方括号包裹参数名参数名会出现在req.query里。比如// pages/api/users/[id].ts import type { NextApiRequest, NextApiResponse } from next; export default function handler(req: NextApiRequest, res: NextApiResponse) { const { id } req.query; res.status(200).json({ id }); }请求GET /api/users/42req.query.id的值就是字符串42。这里有个官方文档写得不太显眼的细节query 参数的类型可能是string或string[]。当 URL 出现/api/users/42?tagatagb时req.query.tag是[a, b]。如果你用req.query.id直接拼进 SQL 或存储查询必须先做一次类型收敛const id Array.isArray(req.query.id) ? req.query.id[0] : req.query.id; if (!id || typeof id ! string) { res.status(400).json({ error: Invalid id }); return; }动态参数的命名尽量简短且语义明确。[id]、[slug]、[username]都行但别用[userId]和[user_id]混着来一个项目里风格必须统一。另外方括号里的名字不能包含路径分隔符/也就是说[a/b].ts这种文件在文件系统层面都创建不出来在命名阶段就不合法的。2.3 捕获所有路由[...param].ts的边界捕获所有路由用[...param]表示它匹配一级或多级路径。文件pages/api/files/[...path].ts可以匹配/api/files/a/api/files/a/b/api/files/a/b/c对应的req.query.path是一个字符串数组例如/api/files/a/b/c会得到[a, b, c]。这个模式特别适合做文件系统映射、代理转发、或者为多个子路径提供统一的处理逻辑。但需要注意一个匹配边界[...path].ts不匹配零级路径也就是/api/files本身不会命中这个文件。如果希望/api/files也能被捕获需要用可选捕获所有路由[[...path]].ts两个方括号嵌套。它可以匹配零级、一级、多级路径但代价是req.query.path可能是undefined零级时代码里必须判空// pages/api/files/[[...path]].ts import type { NextApiRequest, NextApiResponse } from next; export default function handler(req: NextApiRequest, res: NextApiResponse) { const path req.query.path; if (!path) { res.status(200).json({ path: [] }); return; } const segments Array.isArray(path) ? path : [path]; res.status(200).json({ segments }); }捕获所有路由能解决很多实际问题但也容易引发命名的优先级困惑。比如pages/api/users/new.ts和pages/api/users/[id].ts同时存在时访问/api/users/new会命中谁Next.js 的规则是静态路由优先于动态路由所以new.ts会先被匹配[id].ts只有在路径不是new时才会接管。这一点后面在优先级章节里再细说。2.4 文件扩展名对路由的影响可能有人会问.ts、.tsx、.js、.jsx这些扩展名会影响 URL 吗答案是不会。pages/api/hello.ts和pages/api/hello.js对应的都是/api/hello扩展名只决定编译方式不参与 URL 匹配。但同一个路径下不能同时存在多个扩展名的同名文件hello.ts和hello.js同时存在会被判为重复路由。同理[id].ts和[id].js在路径层面也是冲突的。实际项目里建议统一用 TypeScript.ts一方面类型约束对 API handler 特别有用另一方NextApiRequest、NextApiResponse这些类型定义也能在编译阶段帮你拦住很多低级错误。3. App Router 的route.ts命名新约定3.1 为什么文件名固定为route而不是自由命名App Router 发布了route.ts作为 API 文件的标准名。这个命名看起来“不自由”其实是刻意设计的App Router 把文件夹当作路由段的唯一来源文件只负责实现这个路由段的行为。route.ts就是“该路由段的处理器”page.tsx就是“该路由段的页面 UI”。两者可以共存也可以只存在其一。你可以在app/api/hello/route.ts新建一个接口它对应/api/hello// app/api/hello/route.ts import { NextResponse } from next/server; export async function GET() { return NextResponse.json({ message: Hello }); }注意到没有默认导出的 handler而是具名导出 HTTP 方法函数。这是 App Router 和 Pages Router 最大的不同不再用export default统一处理而是直接用export const GET、export const POST等。这个设计让文件结构更清晰一个文件里同时导出多个方法时可读性比 Pages Router 里的req.method分支好得多。3.2route.ts与page.tsx的同目录共存规则一个文件夹下route.ts和page.tsx可以同时存在。route.ts处理/api/xxx的接口请求page.tsx处理/xxx的页面访问两者互不干扰。这个特性在 Next.js 13.4 之后是稳定的此前版本会报错升级到 14/15 版本后基本没这个问题。但下面这种场景会冲突在同一个路径层级既想用route.ts处理/api/xxx又想用page.tsx处理/api/xxx也就是让同一个 URL 既能返回 JSON 又能返回 HTMLNext.js 会直接启动失败提示page.tsx和route.ts不能指向同一个路由节点。因为这两个文件在路由表中代表的是同一个 URL 段上的两种处理方式框架不允许二义性。实际写业务时API 和页面本身就应该分开很少需要这种操作。3.3 App Router 下的动态段命名App Router 的动态路由是在文件夹名上加方括号和 Pages Router 的结构完全对称app/api/users/[id]/route.ts这个文件对应/api/users/123动态参数通过context.params获取// app/api/users/[id]/route.ts import { NextResponse } from next/server; export async function GET( _request: Request, context: { params: Promise{ id: string } } ) { const { id } await context.params; return NextResponse.json({ id }); }注意在 Next.js 15 版本里context.params变成了Promise需要await才能取到值。这块忘了await的话拿到的会是一个 Promise 对象接口能跑但数据永远不对排查起来很隐蔽。动态段命名建议用小写英文加连字符比如[order-id]避免出现大写字母加下划线这种风格。虽然 Next.js 允许但在 URL 编码、边缘缓存、团队协作场景下小写连字符是最稳妥的选择。3.4 捕获所有段在文件夹命名中的表示App Router 的捕获所有路由也通过文件夹命名实现app/api/files/[...path]/route.ts匹配/api/files/a、/api/files/a/b不匹配/api/filesapp/api/files/[[...path]]/route.ts匹配零级到多级import { NextResponse } from next/server; export async function GET( _request: Request, context: { params: Promise{ path?: string[] } } ) { const { path } await context.params; return NextResponse.json({ path: path ?? [] }); }这里path的类型是string[] | undefined需要默认值兜底。和 Pages Router 不同App Router 的捕获段参数在类型上已经明确是数组少了Array.isArray的判断但多了Promise的处理心智负担没有变轻太多。4. 方法导出、文件名与请求处理的关系4.1 同一文件多方法导出的写法差异Pages Router 的 handler 里靠req.method分支// pages/api/users.ts import type { NextApiRequest, NextApiResponse } from next; export default function handler(req: NextApiRequest, res: NextApiResponse) { switch (req.method) { case GET: // 返回用户列表 res.status(200).json([]); break; case POST: // 创建用户 res.status(201).json({ ok: true }); break; default: res.setHeader(Allow, [GET, POST]); res.status(405).end(Method ${req.method} Not Allowed); } }App Router 就优雅多了同名文件直接导出同名函数// app/api/users/route.ts import { NextResponse } from next/server; export async function GET() { return NextResponse.json([]); } export async function POST(request: Request) { const body await request.json(); return NextResponse.json({ ok: true }, { status: 201 }); }这两套写法在“文件命名”语境下的关联点在于单个文件能承载的 HTTP 方法决定了它的命名是否合理。如果一个文件的逻辑只处理一个动作命名可以具体一些比如pages/api/users/getProfile.ts如果文件承载了完整的 RESTful 操作GET/POST/PUT/DELETE命名就应该用资源名比如pages/api/users.ts。别把后者拆成getUsers.ts、createUser.ts三个文件——那是在拆散同一个资源的聚合逻辑反而让 URL 更碎。4.2 未导出的方法返回什么Pages Router 里如果客户端发来一个PATCH请求但 handler 里没写对应分支代码会走到你default里返回 405如果没写default又会落入res.end()之外的空操作连接卡住最坏情况导致请求超时。App Router 更省心route.ts只导出了GET和POST那其他方法会由框架自动返回405 Method Not Allowed响应头里还会带上Allow字段。这算是从框架层面解决了方法遗漏的问题但如果你用的是 Pages Router建议所有 handler 都加上 405 兜底分支这是真实线上环境最容易忽略的细节。4.3 命名与请求/响应类型的配合Pages Router 用NextApiRequest和NextApiResponse这两个类型来自next包提供了req.query、req.body、res.status()、res.json()等常用能力。App Router 则直接使用标准 Web API 的Request和NextResponse前者是运行时统一的标准请求对象后者是 Next.js 对响应做的增强封装。在命名层面影响不大但容易混淆。不少从 Pages Router 迁到 App Router 的代码会把NextApiRequest用在route.ts里编译报错才意识到类型体系换了。建议新项目直接上 App Router老项目也别急着全部迁移Pages Router 在 Next.js 15 里依然稳定支持不会短期内被移除。5. 动态路由优先级与命名冲突的完整解读5.1 静态、动态、捕获所有的匹配优先级当一个请求路径同时可能命中多个文件时Next.js 的匹配顺序是固定的理解这个顺序能帮你避免一堆疑难杂症。规则如下静态命名优先users/new.tsusers/[id].tsusers/[...path].ts动态段数量少的优先users/[id]/posts.ts优先于users/[id]/posts/[postId].ts可选捕获所有优先级最低[[...path]].ts基本是“最后兜底”这里最容易出问题的场景是pages/api/users/[id].ts和pages/api/users/me.ts同时存在前端调用/api/users/me时命中me.ts这可能和你预期的[id]处理逻辑不一致。如果要让me这个路径走动态路由而不是静态文件唯一的方式是删掉me.ts用[id].ts里的逻辑去判断id me。静态优先是写死的约定你想覆盖它就得往约定内部做逻辑而不是在文件系统层面硬碰硬。5.2 动态参数名不能重复的规则在一个路径里动态参数名不能重复。比如app/api/[id]/posts/[id]/route.ts两个段都叫idNext.js 会直接报“You cannot use the same parameter name twice”的构建错误。这个约束对 Pages Router 同样生效pages/api/[user]/[user].ts是不合法的。命名时必须让每一层的动态参数名唯一推荐按语义区分[userId]、[postId]、[commentId]。5.3 大小写敏感的隐藏规则文件系统分大小写Next.js 的路由匹配同样区分大小写。pages/api/Users.ts对应/api/Users/api/users会 404。这个问题在 macOS 上最容易踩坑因为 macOS 默认文件系统APFS大小写不敏感你在本地创建了Users.ts访问/api/users也能通代码一推到 Linux 服务器大小写敏感接口立刻全部失效。我在项目里遇到过最离奇的一次排查就是本地开发一切正常部署到容器里POST /api/login全部 401查了半天发现文件写的是pages/api/Login.ts本地 macOS 上/api/login和/api/Login都能命中同一个文件Linux 上却只能命中/api/Login前端调用的路径是小写所以全挂。这个坑没有任何报错信息日志里只有 404排查成本极高。建议团队规范里强制小写命名大小写不敏感的开发环境根本不是帮你而是在帮你掩盖问题。5.4 路径分隔与 URL 编码中文、空格、特殊字符理论上可以出现在文件名里但绝不建议。一方面URL 里这些字符会被 percent-encoding 转义比如文件名我的接口.ts对应 URL/api/%E6%88%91%E7%9A%84%E6%8E%A5%E5%8F%A3前端代码可读性极差另一方面一些反向代理和 Web 服务器在路径解码上行为不一致很容易导致接口在部分环境下可用、部分环境下 404。如果要表达中文或带空格的资源名用一串英文连字符替代语义完全可以在代码注释里补充。文件名是给人看的URL 也是给人看的别为了省事制造双重心智负担。6. 命名规范实战建议与团队协作6.1 小写连字符kebab-case作为唯一标准Next.js 官方没有强制命名风格但社区主流是一致的统一使用小写字母加连字符kebab-case。原因包括Linux 服务器大小写敏感小写避免部署环境不一致URL 里连字符不用转义下划线在部分网关和 CDN 里有时会被特殊处理小写连字符在文件名和 URL 之间可以直接画等号不需要心算大小写转换接口文件的具体命名可以按资源类型细分类型命名示例对应 URL集合资源pages/api/orders.ts/api/orders单资源pages/api/orders/[order-id].ts/api/orders/42子资源pages/api/orders/[order-id]/items.ts/api/orders/42/items动作型接口pages/api/auth/login.ts/api/auth/login批量操作pages/api/orders/batch.ts/api/orders/batch6.2 版本管理/api/v1的目录设计绝大多数 SaaS 系统需要维护多个 API 版本这时在目录层面做版本拆分最清晰pages/api/v1/orders.ts pages/api/v2/orders.ts对应 URL 分别为/api/v1/orders和/api/v2/orders。App Router 同理app/api/v1/orders/route.ts app/api/v2/orders/route.ts这样命名有两点好处一是新旧版本可以并行上线前端灰度切流时有明确的路由边界二是目录本身成了版本说明文档任何人打开项目都能一眼看出当前维护了几个 API 版本。注意不要在文件名里加v1后缀ordersV1.ts这种版本信息属于路由层级不属于资源命名两者混在一起会让 URL 变得非常难维护。6.3 团队 PR 评审中的命名自查项给团队项目做代码评审时我通常会重点看三类命名问题一是动态参数名是否有语义[id]到处用的话代码里req.query.id满天飞根本分不清是哪一层的数据二是 API 文件是否和业务模块目录对应比如订单相关接口就应该在orders/目录下而不是散落在common/里三是方法导出是否和文件名语义匹配比如user.ts只导出了GET而没有任何写入操作要拉齐团队成员判断是否存在遗漏。在提交代码之前也可以在本地跑一次next build它会检查路由冲突和重复命名构建报错比线上 404 要友好得多。7. 常见命名问题速查表我把平时遇到的高频问题整理成一个速查表按现象对比定位排查时可以直接对照问题现象可能原因解决方案访问/api返回 404缺少pages/api/index.ts或app/api/route.ts补上索引文件访问/api/users返回 404文件名写成了users.tsx或user.ts检查文件后缀和拼写生产环境 404本地正常文件名包含大写字母Linux 大小写敏感全部改为小写连字符动态路由不生效[id].ts被同级静态文件抢占改用不冲突的静态路径动态参数是数组而非字符串请求带了多个同名 query 参数用Array.isArray做收敛App Router 接口全部 404route.ts被命名为自定义文件改回标准名route.ts访问/api/files不命中捕获路由[...path]不匹配零级路径改成[[...path]]同名文件.ts和.js共存路由冲突只保留一种扩展名请求返回 405Pages Router 缺少方法分支补全所有 HTTP 方法的处理这张表之外还有一个关键点任何路由变更后都建议先刷新浏览器缓存再测。Next.js 开发模式下路由是热更新的但有时旧的编译产物会驻留在内存里表现成接口“明明改了还是老结果”。虽然这种状态在重新编译后会消失但排查阶段会浪费很多时间。8. 从命名出发的两条进阶建议8.1 用命名反推接口设计是否合理文件命名从来不只是一个“叫什么”的问题它能反映接口设计的好坏。如果一个文件名叫pages/api/misc.ts、pages/api/doEverything.ts说明这个接口职责过重建议拆分成多个资源文件。如果一个动态参数名是[type]但代码里靠字符串值去判断执行逻辑这通常说明路由设计有瑕疵——更合理的做法是把这个类型拆成独立的文件通过文件系统路由天然分流。在前后端联调时接口文档的第一行通常会写路径这个路径就是文件名映射出来的。路径如果自己都读不通前后端沟通就会产生大量不必要的对齐成本。8.2 命名与中间件的收纳位置还有一类“命名”容易被忽略Next.js 的中间件文件middleware.ts必须放在项目根目录或src目录下不能放进pages/api或app/api。中间件文件不算 API 路由但它的命名和位置会直接影响所有 API 路由的执行顺序。如果你曾尝试用中间件做接口鉴权结果发现不生效先检查文件位置对不对再检查导出的函数名是不是middleware。这个文件位置规则虽然不属于“API 路由文件命名”本身但它和 API 接口的暴露范围紧密相关做鉴权、日志、请求 ID 注入时一定会遇到顺手提一下能少走很多弯路。在实际项目中摸爬滚打一圈之后我最大的感受是Next.js 的文件命名不是一个小细节它直接决定了接口的可维护性和可靠性。很多问题从报错日志上看是 404、405但根因就是命名不满足约定。新写文件之前花十秒钟想清楚两层结构目录代表资源层级、文件名代表动作或资源标识比事后排查小写字母和动态路由冲突要省力得多。如果你正在做项目迁移或者从零搭新服务建议把命名规范直接写进团队的开发约定里让所有 API 文件都按照同一套规则生长后面维护起来的顺畅度会超出预期。