项目背景#

试着把项目从 Node.js 迁移到 Next.js，想在 Vercel 上跑起来。

原来 Node.js 的结构：

1
blog-like-api/
2
├── api/
3
│   └── like.ts
4
├── page/
5
│   └── index.ts
6
└── package.json

迁移到 Next.js 后变成了：

1
blog-like-api/
2
├── pages/
3
│   ├── api/
4
│   │   └── like.ts      →  /api/like
5
│   └── index.ts         →  /
6
├── package.json
7
└── ...

但在 Vercel 上跑不通 —— Vercel 检测不出这是 Next.js，所有文件都当静态文件处理，API 路由直接失效。加了 vercel.json 指定框架后问题才解决。

换了 Next.js 后的遭遇#

按照 Next.js 的约定式路由，pages/api/like.ts 应该映射到 /api/like。

但 Vercel 返回：

1
Cannot GET /api/like

Vercel 没有识别出这是 Next.js 项目。

解决方案：指定 framework#

需要创建 vercel.json 强制指定框架：

1
{
2
    "framework": "nextjs"
3
}

加上这个配置后，Vercel 才正确识别 Next.js 框架，API 路由才正常工作。

自动检测原理#

Vercel 部署时会自动检测项目使用的框架，检测依据包括：

检测失败的后果#

当 Vercel 检测为 None（框架未知）时：

Vercel 会默认将项目当作”纯静态站点”处理。此时 Next.js 的 API 路由功能不会被启用，所有 pages/api/* 或 app/api/* 的文件都不会被当作 API 端点。

具体来说：

• pages/api/like.ts 这类 API 文件，在部署后不会被编译成 Serverless Function
• 相反，它们会被当作普通的静态资源文件处理
• 访问 /api/like 时，Vercel 找不到对应的端点，返回 404 或 Cannot GET 错误

这就是为什么即使你正确放置了 pages/api/like.ts，访问 /api/like 依然会返回 404。

可能误判的原因#

1
{
2
    "dependencies": {
3
        "react": "^18.0.0",
4
        "vue": "^3.0.0",
5
        "next": "^14.0.0"
6
    }
7
}

何时需要 vercel.json，何时可以依赖自动检测#

如何确认是否检测正确#

查看 Vercel 构建日志。在 Vercel 控制台：

1. 进入 Deployments 页面
2. 选择对应的部署
3. 点击对应的部署进入详情页
4. 在 Logs 标签下查看构建日志

日志中会显示框架检测结果：

1
[INFO] Detected Framework: Next.js  ← 正确识别
2
[INFO] Detected Framework: None      ← 检测失败，需要手动指定

vercel.json 配置#

创建 vercel.json 文件明确指定框架：

1
{
2
    "framework": "nextjs"
3
}

支持的框架值#

重要：选择正确的 framework 值至关重要。不同的框架值会触发 Vercel 完全不同的构建流程和路由规则。

错误选择的风险：如果错误地将 "framework" 设置为 "static"，即使你的文件结构完全正确，Next.js 的 API 路由也会被彻底禁用。这是因为 "static" 会告诉 Vercel 这是一个纯静态站点，不会启动任何 API 路由编译流程。

这些值是 Vercel 官方文档中定义的标准标识符，具体支持情况请以 Vercel 官方文档 为准。

vercel.json 完整配置示例#

1
{
2
    "framework": "nextjs",
3
    "buildCommand": "npm run build",
4
    "devCommand": "npm run dev",
5
    "installCommand": "npm install"
6
}

错误一：Vercel 没识别出框架#

1
❌ Cannot GET /api/like
2
✅ 添加 vercel.json 指定 framework

解决：

1
{
2
    "framework": "nextjs"
3
}

错误二：Pages 和 App 路由混用#

1
❌ pages/api/like/route.ts（不存在的结构）
2
✅ pages/api/like.ts（Pages 路由）
3
✅ app/api/like/route.ts（App 路由）

错误三：以为是 Express 的自定义路由#

常见认知误区：许多从 Express 转来的开发者，习惯了代码定义路由，容易误以为 Next.js 也可以通过配置自定义路由路径。

实际上，Next.js 的约定式路由是固定的、不可自定义的。你不能把 pages/api/like.ts 映射到 /custom/like，也不能把 app/api/users.ts 映射到 /api/v1/users。

如果你习惯了 Express 中 app.get('/path', handler) 的写法，你可能会误以为 Next.js 也能自定义路径——但这是不成立的。

1
❌ 期望 pages/api/like.ts 映射到 /custom/like
2
✅ Next.js 不能自定义路由路径

错误四：buildCommand 不正确#

1
{
2
    "framework": "nextjs",
3
    "buildCommand": "npm run build",
4
    "devCommand": "npm run dev",
5
    "installCommand": "npm install"
6
}

Pages 路由（pages/ 目录）#

这是 Next.js 传统的路由方式：

1
文件系统                    →  URL 路径
2
pages/
3
    ├── index.ts          →  /
4
    ├── about.ts          →  /about
5
    ├── contact.ts        →  /contact
6
    ├── api/
7
    │   ├── like.ts       →  /api/like
8
    │   ├── users.ts      →  /api/users
9
    │   └── users/
10
    │       └── index.ts   →  /api/users
11
    └── posts/
12
        ├── index.ts      →  /posts
13
        └── [slug].ts     →  /posts/123（动态路由）

App 路由（app/ 目录，Next.js 13+）#

这是新版路由方式，使用 React Server Components：

1
文件系统                    →  URL 路径
2
app/
3
    ├── page.tsx          →  /
4
    ├── about/
5
    │   └── page.tsx      →  /about
6
    ├── contact/
7
    │   └── page.tsx      →  /contact
8
    ├── api/
9
    │   └── like/
10
    │       └── route.ts  →  /api/like
11
    └── posts/
12
        ├── page.tsx      →  /posts
13
        └── [slug]/
14
            └── page.tsx  →  /posts/123（动态路由）

注意：App 路由中每个页面文件必须命名为 page.tsx（或 page.js），不能使用 index.tsx。这是 Next.js 官方约定的命名规范。

Pages vs App 路由对比#

常见错误：文件放错位置#

重要提醒：即使框架检测正确，文件放错位置同样会导致 404。

1
❌ 将 API 文件放在 public/ 目录下
2
   public/api/like.ts  →  不会映射到 /api/like
3

4
❌ 将 API 文件放在根目录的任意位置
5
   api/like.ts         →  不会映射到 /api/like
6

7
✅ Pages 路由：pages/api/*.ts
8
✅ App 路由：app/api/*/route.ts

Next.js 的约定式路由只认 pages/api/ 和 app/api/ 这两个固定目录，其他位置的 API 文件不会被处理。

对比一览#

核心洞察：使用约定式路由的框架（如 Next.js）将路由逻辑与文件系统强绑定，而代码定义路由（如 Express）则允许在代码中自由定义路径。理解这一点是避免路径混淆的关键。

核心区别#

代码定义路由（如 Express）给予开发者完全的路径控制权，而约定式路由（如 Next.js）则通过文件系统结构隐式定义路径，牺牲了灵活性以换取开发效率和一致性。

Node.js/Express（代码定义路由）：

目录名和路由没有直接关系。page/index.js 不等于 / 路由，只是在代码里挂载为 /：

1
blog-like-api/
2
├── page/
3
│   └── index.js      ←  只是文件名叫 index，不是 /
4
├── api/
5
│   └── like.js       ←  只是文件名叫 like，不是 /api/like
6
└── app.js

1
const pageIndex = require('./page/index');
2
const apiLike = require('./api/like');
3

4
app.use('/', pageIndex);    // page/index.js 里的 get('/') 才映射到 /
5
app.use('/api', apiLike);  // api/like.js 里的 get('/') 才映射到 /api

Next.js（约定式路由）：

文件名直接决定 URL，pages/ 是约定俗成的目录名称（不是固定的，你可以用 app/）：

1
pages/
2
├── index.ts         →  /
3
├── about.ts         →  /about
4
└── api/
5
    └── like.ts     →  /api/like

关键差异：Express 里你可以把 page/index.js 挂载到 /hello，api/like.js 挂载到 /world，完全自由。而 Next.js 不行，pages/api/like.ts 只能映射到 /api/like，不能自定义。

第一步：检查 Vercel 构建日志#

查看是否正确识别了框架。在 Vercel 控制台进入 Deployments → 选择部署 → 在 Logs 标签下查看构建日志：

1
[INFO] Detected Framework: Next.js  ← 正确
2
[INFO] Detected Framework: None      ← 问题在这里

这直接印证了核心结论中的判断：如果检测为 None，说明 Vercel 没有识别出框架，项目被当作纯静态处理。

第二步：添加 vercel.json#

1
{
2
    "framework": "nextjs"
3
}

第三步：检查路由文件位置#

第四步：本地测试#

1
# 安装 Vercel CLI
2
npm i -g vercel
3

4
# 本地运行
5
vercel dev
6
# 通常显示 http://localhost:3000
7

8
# 本地运行后：
9
# pages/api/like.ts → http://localhost:3000/api/like

重要：本地测试无法验证 Vercel 的框架检测机制。vercel dev 主要验证路由逻辑和代码正确性，但它无法模拟 Vercel 的自动检测流程。

本地测试的验证范围：

第五步：健康检查接口#

添加健康检查接口，用于验证部署结果：

1
export default function handler(req, res) {
2
    res.status(200).json({
3
        message: "API 正常",
4
        url: req.url,
5
        method: req.method,
6
        timestamp: new Date().toISOString()
7
    });
8
}

用途：在添加 vercel.json 并重新部署后，立即访问 /api/test 验证 API 路由是否已恢复正常。

健康检查接口的多重用途：

1. 验证部署和路由：确认 API 是否被正确部署和路由
2. 前端健康探测：作为前端应用检测后端服务状态的探测点
3. CI/CD 流程集成：在持续集成/部署流程中作为健康检查端点

推荐做法#

1. 使用 create-next-app 创建项目后，立即添加 vercel.json

   1
   npx create-next-app my-blog --typescript
   2
   cd my-blog
   3
   # 创建 vercel.json
   4
   echo '{"framework": "nextjs"}' > vercel.json

2. 将其纳入版本控制

   确保团队成员和 CI/CD 环境使用相同的配置：

   1
   git add vercel.json
   2
   git commit -m "chore: add vercel.json with explicit framework"

3. 在项目文档中记录

   如果项目有 README，建议在其中记录 vercel.json 的作用，避免其他协作者误删。

核心要点#

1. 换了框架后，Vercel 可能检测不出来 — 需要 vercel.json 强制指定
2. 检测为 None 时，项目被当作纯静态处理 — API 文件不会被编译成 Serverless Function
3. Next.js 用约定式路由 — 文件位置决定 URL，不能自定义
4. Pages 和 App 路由结构不同 — 不要混用
5. 本地测试无法验证框架检测 — 必须以 Vercel 构建日志为准

一句话记住#

Vercel 不一定能猜对框架。当出现”Cannot GET”时，先检查 Vercel 有没有正确识别你的框架。

常见问题速查表#

快速修复清单#

读者行动清单#

1. 检查项目结构：确认是否使用了标准的 Next.js 项目结构（包含 next.config.js、pages/ 或 app/）

2. 查看 Vercel 构建日志：确认框架检测结果是否为 None

3. 如果检测失败：在项目根目录创建 vercel.json，添加 "framework": "nextjs"

4. 确认 API 文件位置：Pages 路由放在 pages/api/*.ts，App 路由放在 app/api/*/route.ts

5. 本地测试：使用 vercel dev 验证路由逻辑

6. 重新部署：触发新的部署流程

   （重要） 添加 vercel.json 后，必须触发一次新的部署（例如 git push），否则配置不会生效。

7. 验证 API 端点：通过健康检查接口 /api/test 或实际端点 /api/like 确认正常工作

vercel.json 最小配置#

1
{
2
    "framework": "nextjs"
3
}

EOF