📦 Vercel 配置分析器

Vercel Config Analyzer 分析 Vercel 项目配置的正确性、性能与安全性。检查 vercel.json、框架设置、构建配置、edge functions、middleware、headers、redirects、环境变量及部署模式，在上线前发现配置错误。 适用场景：“review our Vercel config”、“why is our Vercel deployment slow”、“check vercel.json”、“optimize our edge functions”、“fix Vercel build errors”、“audit our headers and redirects”、或首次部署到 Vercel 时。

分析步骤

• 盘点项目配置

定位并读取所有 Vercel 相关文件：

• vercel.json —— 主配置
• 框架配置：next.config.js、nuxt.config.ts、svelte.config.js、astro.config.mjs 等
• package.json —— 构建命令与框架识别
• .env 文件 —— 仅检查存在性，不读内容
• middleware.ts / middleware.js —— edge middleware
• api/ / pages/api/ / app/api/ —— serverless 与 edge functions（搜索 export const runtime）

• 分析 vercel.json

逐节校验： 构建配置示例 { "buildCommand": "npm run build", "outputDirectory": "dist", "installCommand": "npm ci", "framework": "nextjs" } 常见错误

• buildCommand 与 package.json scripts 不符
• outputDirectory 与框架默认目录不符（Next.js: .next，Vite: dist，CRA: build）
• 缺少 framework 字段导致自动识别失败
• 使用 npm install 而非 npm ci（构建不可重复）

框架识别矩阵 Framework | Expected Output Dir | Auto-Detected | Build Command Next.js | .next | Yes | next build Vite | dist | Yes | vite build CRA | build | Yes | react-scripts build Nuxt | .output | Yes | nuxt build SvelteKit | .svelte-kit | Yes | vite build Astro | dist | Yes | astro build Remix | build | Yes | remix build Plain HTML| public 或 . | No | None

• 审计 Headers 配置

{ "headers": [ { "source": "/(.)", "headers": [ { "key": "X-Content-Type-Options", "value": "nosniff" }, … ] } ] }

安全 headers 清单 Header | 必要性 | 目的 | 推荐值 Strict-Transport-Security | 关键 | 强制 HTTPS | max-age=63072000; includeSubDomains; preload X-Content-Type-Options | 关键 | 防止 MIME 嗅探 | nosniff X-Frame-Options | 高 | 防点击劫持 | DENY 或 SAMEORIGIN Content-Security-Policy | 高 | 防 XSS/注入 | 业务自定义 Referrer-Policy | 中 | 控制引用信息 | strict-origin-when-cross-origin Permissions-Policy | 中 | 限制浏览器功能 | 禁用未用功能 X-XSS-Protection | 低 | 旧版 XSS 过滤器 | 0（或省略，由 CSP 替代）

缓存策略建议 资源类型 | Cache-Control | 理由 哈希资源（JS/CSS） | public, max-age=31536000, immutable | 内容寻址，永不变 图片/字体 | public, max-age=86400, stale-while-revalidate=604800 | 极少变动 HTML 页面 | public, max-age=0, must-revalidate | 需实时更新 API 响应 | no-store 或 private, max-age=60 | 视数据新鲜度 用户数据 | private, no-store | 禁止共享缓存

• 分析 Redirects 与 Rewrites

Redirect 常见问题

• 对临时跳转误用 permanent: true（301 极难清除）
• 跳转链 A→B→C，应合并为 A→C
• 尾斜杠不一致（/about vs /about/）
• 手动 HTTP→HTTPS 跳转 —— Vercel 已自动处理

Rewrite 常见问题

• 外部 API rewrite 缺少 has 条件，形成开放代理
• SPA 通配 /:path* → /index.html 未置最后，覆盖 API 路由
• 外部 rewrite 目标未用 HTTPS
• 规则冲突 —— 匹配顺序决定结果

• 评估 Serverless 与 Edge Functions

可在 vercel.json 配置（per-file memory、maxDuration、runtime），或在代码内使用 export const runtime = 'edge'、export const maxDuration = 30。

函数优化清单

• 冷启动：延迟加载重依赖，缩减包体积（节省 1–5s）
• 内存：简单处理设 128–256 MB（默认 1024 MB 过高）
• 时长：长任务显式设置 maxDuration（Hobby 默认 10s，Pro 60s）
• 运行时选择：

– Edge：auth、geo、A/B 测试，需低延迟 – Serverless：DB 查询、文件处理，需 Node.js API

Edge vs Serverless 决策矩阵 用例 | 推荐运行时 | 原因 认证/授权 | Edge | 低延迟，页面加载前执行 基于地理位置的路由 | Edge | 可访问 request.geo A/B 测试 | Edge | 快速边缘响应 功能开关 | Edge | 边缘快速生效 数据库查询 | Serverless (Node.js) | 驱动依赖 Node.js API