部署配置 #

配置方式概览 #

Vercel 支持多种配置方式：

text

┌─────────────────────────────────────────┐
│           Vercel 配置方式                │
├─────────────────────────────────────────┤
│  vercel.json    →  项目配置文件          │
│  Dashboard      →  图形界面配置          │
│  CLI 参数       →  命令行配置            │
│  环境变量       →  动态配置              │
└─────────────────────────────────────────┘

vercel.json 配置文件 #

基本结构 #

json

{
  "version": 2,
  "name": "my-project",
  "builds": [...],
  "routes": [...],
  "headers": [...],
  "rewrites": [...],
  "redirects": [...]
}

完整配置示例 #

json

{
  "version": 2,
  "name": "my-nextjs-app",
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "installCommand": "npm install",
  "framework": "nextjs",
  "regions": ["hkg1", "sfo1"],
  "functions": {
    "api/**/*.js": {
      "memory": 1024,
      "maxDuration": 10
    }
  },
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Content-Type-Options",
          "value": "nosniff"
        },
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        }
      ]
    }
  ],
  "rewrites": [
    {
      "source": "/api/:path*",
      "destination": "/api/:path*"
    }
  ],
  "redirects": [
    {
      "source": "/old-page",
      "destination": "/new-page",
      "permanent": true
    }
  ]
}

核心配置项 #

项目基础配置 #

配置项	说明	示例
`version`	配置版本	`2`
`name`	项目名称	`"my-project"`
`framework`	框架类型	`"nextjs"`

构建配置 #

json

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "installCommand": "npm install",
  "devCommand": "npm run dev",
  "cleanUrls": true,
  "trailingSlash": false
}

配置项	说明
`buildCommand`	构建命令
`outputDirectory`	输出目录
`installCommand`	安装依赖命令
`devCommand`	开发服务器命令
`cleanUrls`	移除 URL 中的 .html
`trailingSlash`	URL 尾部斜杠

区域配置 #

json

{
  "regions": ["hkg1", "sfo1", "iad1"]
}

可用区域：

区域代码	位置
`hkg1`	香港
`sfo1`	旧金山
`iad1`	华盛顿
`lhr1`	伦敦
`fra1`	法兰克福
`syd1`	悉尼
`sin1`	新加坡
`nrt1`	东京

路由配置 #

Headers（响应头） #

json

{
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "s-maxage=86400"
        },
        {
          "key": "Access-Control-Allow-Origin",
          "value": "*"
        }
      ]
    },
    {
      "source": "/fonts/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}

Rewrites（重写） #

json

{
  "rewrites": [
    {
      "source": "/api/:match*",
      "destination": "https://api.example.com/:match*"
    },
    {
      "source": "/blog",
      "destination": "/blog/index.html"
    },
    {
      "source": "/proxy/:path*",
      "destination": "https://external-api.com/:path*"
    }
  ]
}

Redirects（重定向） #

json

{
  "redirects": [
    {
      "source": "/old-blog/:slug",
      "destination": "/blog/:slug",
      "permanent": true
    },
    {
      "source": "/docs/:path*",
      "destination": "/documentation/:path*",
      "permanent": false
    },
    {
      "source": "/legacy",
      "destination": "/",
      "permanent": true
    }
  ]
}

属性	说明
`source`	匹配的路径模式
`destination`	目标路径
`permanent`	`true` = 308 永久重定向，`false` = 307 临时重定向

路径匹配语法 #

text

┌─────────────────────────────────────────┐
│           路径匹配语法                   │
├─────────────────────────────────────────┤
│  :path        →  匹配单个段             │
│  :path*       →  匹配多个段             │
│  (pattern)    →  正则表达式组           │
│  (?:pattern)  →  非捕获组               │
└─────────────────────────────────────────┘

示例：

json

[
  { "source": "/user/:id", "destination": "/users/:id" },
  { "source": "/files/:path*", "destination": "/storage/:path*" },
  { "source": "/(en|zh)/:path", "destination": "/:path?lang=$1" }
]

函数配置 #

基本配置 #

json

{
  "functions": {
    "api/**/*.js": {
      "memory": 1024,
      "maxDuration": 10,
      "runtime": "nodejs18.x"
    }
  }
}

配置项	说明	范围
`memory`	内存大小（MB）	128 - 3008
`maxDuration`	最大执行时间（秒）	Hobby: 10, Pro: 60, Enterprise: 900
`runtime`	运行时环境	`nodejs18.x`, `nodejs20.x`, `python3.x`

不同路径的函数配置 #

json

{
  "functions": {
    "api/light.js": {
      "memory": 128,
      "maxDuration": 5
    },
    "api/heavy.js": {
      "memory": 3008,
      "maxDuration": 60
    }
  }
}

缓存配置 #

静态资源缓存 #

json

{
  "headers": [
    {
      "source": "/static/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    },
    {
      "source": "/images/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=86400, stale-while-revalidate=3600"
        }
      ]
    }
  ]
}

缓存策略说明 #

text

Cache-Control 值说明：
├── public           →  可被任何缓存存储
├── private          →  仅浏览器缓存
├── max-age=3600     →  缓存 1 小时
├── s-maxage=3600    →  CDN 缓存 1 小时
├── stale-while-revalidate=60  →  过期后 60 秒内可使用旧响应
├── immutable        →  永不过期
└── no-cache         →  每次验证

Ignored Files（忽略文件） #

json

{
  "git": {
    "deploymentEnabled": {
      "exclude": [
        "README.md",
        "docs/**",
        ".vscode/**"
      ]
    }
  }
}

GitHub 配置 #

json

{
  "github": {
    "silent": true,
    "autoJobCancelation": true
  }
}

配置项	说明
`silent`	禁用 PR 评论
`autoJobCancelation`	自动取消进行中的构建

Dashboard 配置 #

项目设置页面 #

text

Project Settings → General
├── Project Name
├── Root Directory
├── Framework Preset
├── Build & Development Settings
│   ├── Build Command
│   ├── Output Directory
│   └── Install Command
└── Ignored Build Step

构建设置 #

text

┌─────────────────────────────────────────┐
│  Build & Development Settings           │
├─────────────────────────────────────────┤
│  Build Command                          │
│  ┌─────────────────────────────────┐    │
│  │ npm run build                   │    │
│  └─────────────────────────────────┘    │
│                                         │
│  Output Directory                       │
│  ┌─────────────────────────────────┐    │
│  │ dist                            │    │
│  └─────────────────────────────────┘    │
│                                         │
│  Install Command                        │
│  ┌─────────────────────────────────┐    │
│  │ npm install                     │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘

CLI 配置 #

部署时指定配置 #

bash

vercel --build-env NODE_ENV=production
vercel --regions hkg1,sfo1
vercel --prod

常用 CLI 参数 #

参数	说明
`--prod`	部署到生产环境
`--regions`	指定部署区域
`--build-env`	设置构建环境变量
`--force`	强制重新构建
`--yes`	跳过确认

配置优先级 #

text

配置优先级（从高到低）：
1. CLI 参数
2. 环境变量
3. vercel.json
4. Dashboard 设置
5. 框架默认值

下一步 #

掌握部署配置后，接下来学习框架预设支持了解各框架的具体配置！