Vercel.json详解

vercel.json 是 Vercel 平台的核心配置文件，它允许开发者对项目的部署行为、路由规则、Serverless Functions 配置、环境变量、构建过程等进行细粒度的控制。通过 vercel.json，你可以超越 Vercel 的默认零配置行为，根据项目的特定需求定制化部署策略。

核心思想：vercel.json 是一个 JSON 文件，用于声明 Vercel 项目的各种配置，包括路由重写、重定向、HTTP Headers、Serverless Functions 设置、构建步骤和环境变量等，从而实现高级部署功能和优化。

一、`vercel.json` 的基本结构与作用

vercel.json 文件通常位于项目的根目录下。Vercel 在每次部署时会读取这个文件，并根据其中的配置来处理构建、路由和请求。

一个典型的 vercel.json 结构如下：

{
  "version": 2,
  "name": "my-vercel-project",
  "builds": [],
  "routes": [],
  "env": {},
  "public": true,
  "rewrites": [],
  "redirects": [],
  "headers": [],
  "functions": {},
  "github": {
    "silent": true
  }
}

主要作用：

路由控制：定义如何处理传入的请求 URL，包括重写 (rewrites)、重定向 (redirects) 和设置 HTTP 头 (headers)。
Serverless Functions 配置：为 Serverless Functions（包括 Next.js API Routes 和 Edge Functions）设置运行时、内存、超时时间、环境变量等。
构建过程定制：调整 Vercel 的默认构建命令和输出目录。
环境变量管理：在部署时注入环境变量。
项目元数据：设置项目名称、是否公开等。

二、`vercel.json` 核心配置项详解

2.1 `version` (必需)

类型: number
说明: 指定配置文件的版本。目前推荐使用 2。
示例:
1
2
3
{
"version": 2
}

2.2 `name`

类型: string
说明: 指定 Vercel 项目的名称。如果未指定，Vercel 会从 package.json 或 Git 仓库名称中推断。
示例:
1
2
3
{
"name": "my-custom-app"
}

2.3 `builds`

类型: array of object
说明: 定义构建器 (Builders) 和构建配置。通常用于部署非零配置支持的框架或自定义构建流程。
- src: 源文件或目录的 glob 模式。
- use: 使用哪个 Vercel Builder。
- config: 传递给 Builder 的配置。

示例 (部署一个 Go Serverless Function):

{
  "version": 2,
  "builds": [
    {
      "src": "api/go-function.go",
      "use": "@vercel/go",
      "config": { "maxLambdaSize": "10mb" }
    }
  ]
}

注意：对于 Next.js 项目，Vercel 会自动使用 @vercel/next Builder，通常无需手动配置 builds。

2.4 `routes`

类型: array of object
说明: 定义通用的路由规则。routes 数组中的每个对象可以包含 src, dest, methods, headers, status 等属性，以匹配传入请求并指定如何处理。这是一个强大的通用路由机制，但通常更推荐使用更具体的 rewrites, redirects, headers。

示例:

{
  "version": 2,
  "routes": [
    { "src": "/api/old-endpoint", "dest": "/api/new-endpoint", "status": 307 },
    { "src": "/admin/(.*)", "dest": "/admin-dashboard", "status": 200, "headers": { "X-Robots-Tag": "noindex" } }
  ]
}

2.5 `rewrites`

类型: array of object
说明: 将匹配的 URL 重写到另一个内部路径，用户浏览器中的 URL 不会改变。
- source: 匹配的传入 URL 路径 (可以使用 glob 或正则表达式)。
- destination: 重写到的内部路径。

示例 (将 /api/ 重写到 Serverless Function)*:

{
  "version": 2,
  "rewrites": [
    { "source": "/api/(.*)", "destination": "/api" },
    { "source": "/blog/:slug", "destination": "/blog/[slug]" } // Next.js 动态路由
  ]
}

2.6 `redirects`

类型: array of object
说明: 将匹配的 URL 重定向到另一个 URL，并返回相应的 HTTP 状态码（如 301 永久重定向，307 临时重定向）。用户浏览器中的 URL 会改变。
- source: 匹配的传入 URL 路径。
- destination: 重定向到的目标 URL。
- permanent: true (308 永久重定向) 或 false (307 临时重定向)。

示例:

{
  "version": 2,
  "redirects": [
    { "source": "/old-path", "destination": "/new-path", "permanent": true },
    { "source": "/docs", "destination": "https://docs.example.com", "permanent": false }
  ]
}

2.7 `headers`

类型: array of object
说明: 为匹配的 URL 添加自定义 HTTP 响应头。常用于设置 CORS、安全策略等。
- source: 匹配的传入 URL 路径。
- headers: 要添加的 HTTP 头数组。

示例 (设置 CORS 头和安全头):

{
  "version": 2,
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "*" },
        { "key": "X-Frame-Options", "value": "DENY" }
      ]
    },
    {
      "source": "/static/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "max-age=31536000, immutable" }
      ]
    }
  ]
}

2.8 `env`

类型: object
说明: 定义部署时注入到构建和 Serverless Functions 中的环境变量。
- 注意：env 中定义的变量是公开可见的（在构建输出中），不适合存放敏感信息。敏感信息应通过 Vercel UI 或 Vercel CLI (使用 vercel env add) 添加为 Secret。

示例:

{
  "version": 2,
  "env": {
    "PUBLIC_API_URL": "https://api.example.com/v1"
  }
}

2.9 `functions`

类型: object
说明: 为 Serverless Functions (包括 Next.js API Routes 和 Edge Functions) 提供细粒度的配置，如内存、最大执行时间、运行时等。
- 键是函数路径的 glob 模式。
- 值是函数配置对象。

示例 (为特定 API Route 设置更大内存和更长超时):

{
  "version": 2,
  "functions": {
    "api/heavy-computation.js": {
      "memory": 1024,
      "maxDuration": 300 // 5 minutes
    },
    "api/auth/**/*.js": { // 匹配 api/auth 下的所有函数
      "runtime": "nodejs18.x"
    }
  }
}

对于 Next.js 的 Edge Functions 和 Middleware，也可以在此处配置。

2.10 `outputDirectory`

类型: string
说明: 指定项目的构建输出目录。如果 Vercel 无法自动检测，或者你需要自定义输出目录，可以使用此项。对于 Next.js 项目，通常是 .next。

示例:

{
  "version": 2,
  "outputDirectory": "dist"
}

2.11 `installCommand`, `buildCommand`, `devCommand`

类型: string
说明: 自定义项目的安装、构建和开发命令。Vercel 会自动尝试检测，但如果需要特定命令，可以设置。
- installCommand: 依赖安装命令 (如 npm install 或 yarn install)。
- buildCommand: 项目构建命令 (如 next build 或 npm run build)。
- devCommand: 本地开发命令 (如 next dev 或 npm run dev)。

示例:

{
  "version": 2,
  "installCommand": "pnpm install",
  "buildCommand": "pnpm build",
  "devCommand": "pnpm dev"
}

2.12 `regions`

类型: array of string
说明: 指定 Serverless Functions (AWS Lambda) 部署的区域。Edge Functions 默认部署到所有边缘节点。

示例 (将 Lambda 函数部署到 us-east-1 和 eu-central-1):

{
  "version": 2,
  "regions": ["us-east-1", "eu-central-1"]
}

2.13 `git`

类型: object
说明: 配置与 Git 相关的行为。
- deploymentReady (boolean): 是否在 Git 仓库收到更新时立即部署，默认为 true。
- silent (boolean): 是否在 Pull Request/Merge Request 上禁用 Vercel 的部署评论。

示例:

{
  "version": 2,
  "git": {
    "silent": true,
    "deploymentReady": false // 需要手动触发部署
  }
}

三、`vercel.json` 示例 (一个包含多种配置的场景)

{
  "version": 2,
  "name": "my-complex-nextjs-app",
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/next",
      "config": { "maxLambdaSize": "50mb" }
    }
  ],
  "rewrites": [
    {
      "source": "/dashboard",
      "destination": "/dashboard/overview"
    },
    {
      "source": "/app/(.*)",
      "destination": "/_app-private"
    },
    {
      "source": "/cdn/(.*)",
      "destination": "https://cdn.example.com/$1"
    }
  ],
  "redirects": [
    {
      "source": "/legacy-page",
      "destination": "/new-page",
      "permanent": true
    },
    {
      "source": "/old-docs/(.*)",
      "destination": "https://docs.example.com/$1",
      "permanent": false
    }
  ],
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Strict-Transport-Security", "value": "max-age=63072000; includeSubDomains; preload" }
      ]
    },
    {
      "source": "/_next/static/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ],
  "env": {
    "NEXT_PUBLIC_APP_ENV": "production",
    "ANALYTICS_ID": "@analytics_id" // 引用 Vercel Secret
  },
  "functions": {
    "api/auth/*.js": {
      "memory": 256,
      "maxDuration": 10
    },
    "api/webhook.js": {
      "memory": 1024,
      "maxDuration": 60,
      "runtime": "nodejs16.x"
    },
    "middleware.js": { // Next.js Middleware 作为 Edge Function
      "runtime": "edge"
    }
  },
  "public": false,
  "outputDirectory": "out",
  "git": {
    "silent": true
  }
}

四、最佳实践与注意事项

版本控制：vercel.json 文件应始终纳入你的 Git 版本控制，以便团队协作和部署历史追踪。
敏感信息：不要在 vercel.json 中直接存储敏感信息（如 API 密钥、数据库凭据）。使用 Vercel UI 或 CLI 添加为环境变量 Secret (vercel env add)，然后在 vercel.json 的 env 字段中通过 @secret_name 的形式引用。
匹配顺序：routes, rewrites, redirects, headers 数组中的规则是从上到下依次匹配的。第一个匹配到的规则会生效。通常，更具体的规则应放在前面。
source 模式：可以使用通配符 (*)、命名参数 (:slug) 和正则表达式 ((.*))。
Next.js 零配置：对于 Next.js 项目，Vercel 提供了强大的零配置支持。只有当默认行为不满足需求时，才需要使用 vercel.json 进行定制。例如，API Routes 自动成为 Serverless Functions，通常无需在 builds 或 functions 中显式配置。
调试：在本地使用 vercel dev 命令可以在本地环境中测试 vercel.json 的大部分路由和函数配置。
public 属性：设置为 false 可以限制对预览部署的访问，只有 Vercel 团队成员才能查看，但生产部署仍然是公开的。

五、总结

vercel.json 是 Vercel 平台的一个强大工具，它提供了高度的灵活性来定制你的 Web 应用的部署和运行方式。从简单的重定向到复杂的 Serverless Functions 配置，vercel.json 能够帮助开发者优化性能、增强安全性、改善用户体验，并精细控制项目的各个方面。熟练掌握 vercel.json 的使用是充分发挥 Vercel 前端云潜力的关键。

一、vercel.json 的基本结构与作用

二、vercel.json 核心配置项详解

2.1 version (必需)

2.2 name

2.3 builds

2.4 routes

2.5 rewrites

2.6 redirects

2.7 headers

2.8 env

2.9 functions

2.10 outputDirectory

2.11 installCommand, buildCommand, devCommand

2.12 regions

2.13 git

三、vercel.json 示例 (一个包含多种配置的场景)