Vercel 部署后全站 404 排查记

第一步：确认是部署产物问题而非缓存#

本地 pnpm dev 正常，dist/ 里 37 个 index.html 都在。为了排除中间层 CDN 缓存，带随机 query 重新请求，仍然是 404。查看响应头：

1
server: Vercel
2
x-vercel-cache: HIT

404 是源站（Vercel 边缘）自己返回的，不是 CDN 缓存了旧响应。

第二步：对比「部署文件列表」与「本地产物」#

通过 Vercel API 拉取最新部署的文件列表：

1
curl -H "Authorization: Bearer $TOKEN" \
2
  "https://api.vercel.com/v13/deployments/<id>/files"

结果出乎意料：37 个 HTML 文件全部在部署里，路径也都正确（posts/astbot/index.html、about/index.html 等）。文件在、路径对，线上却 404 —— 说明文件内容在服务端无效。

第三步：找到 cleanUrls 冲突#

本地执行 vercel build --prod 后检查生成的 .vercel/output/config.json，发现 CLI 生成了大量 overrides 和 308 重定向规则：

1
{
2
  "overrides": {
3
    "index.html": { "path": "index" },
4
    "about/index.html": { "path": "about/index" }
5
  },
6
  "routes": [
7
    { "src": "^/(?:(.+)/)?index(?:\\.html)?/?$", "headers": { "Location": "/$1" }, "status": 308 }
8
  ]
9
}

这就是问题一：vercel.json 里的 "cleanUrls": true 会让 CLI 把所有 HTML 文件”改名为无扩展名”（about/index.html → about/index）。于是：

• 请求 /about/ 走目录解析，找 about/index.html —— 不存在（已被改名）；
• 请求 /about/index —— 被 308 重定向规则切到 /about；
• /about 又找不到文件 —— 404。

而 /404 之所以能 200，是因为它不在重定向规则里、能直接命中改名后的 404 文件。

修复后，404 页面本身回归正确 404，/、/about/ 等一级页面全部 200。但 /posts/、/gallery/、/dynamic/ 依旧 404 —— 还有第二个问题。

第四步：定位真正的元凶 —— l2s 上传 bug#

继续对比，发现一个奇怪规律：有一级子目录的「父目录」全部 404，纯叶子目录全部 200：

1
/about 200    /archive 200    /search 200
2
/posts 404    /gallery 404    /dynamic 404     （这三个目录里还有子目录）

此时检查本地 .vercel/output/static/ 里的文件类型，真相大白：

1
output/static/about/index.html      # 普通文件 529060 字节（正常）
2
output/static/posts/astbot/index.html -> /home/qwc/Firefly/dist/posts/astbot/.l2s..l2s.index.html0001.00010001   （符号链接！）

Vercel CLI 58.7.1 的 l2s 上传优化在处理大文件时，把 index.html 替换成了指向失效路径的符号链接（symlink），真实数据被写进了 .l2s.index.html0001.0002 分片文件。上传时 Vercel 把这些符号链接原样记录（目标路径在服务器上不存在），于是:

• HTML 在文件列表里”存在”，但服务端读取时解析不到 → 404；
• about/index.html 是硬链接（保留真实文件）→ 正常；
• wrangler（Cloudflare）上传时会跟随符号链接读到真实内容 → CF 完全正常。

这也解释了为什么 CI 部署时上传只有 19.8MB（大量符号链接被跳过/去重），而实际产物有 52MB。

为什么 Cloudflare / EdgeOne 不受影响#

同一份 dist，三家平台的部署工具走的是完全不同的上传模型：

wrangler / edgeone 是朴素的”文件内容上传”模型，没有本地预处理这一层，符号链接在读文件时就被解析掉了，自然不受影响。Vercel CLI 因为多了 l2s 预处理层，才把 bug 带进了部署产物。多平台部署（CF / EdgeOne / Vercel）在这种场景下相当于交叉验证：同一份 dist，别人正常、只有 Vercel 异常，问题几乎可以锁定在 Vercel 的部署链路上。

直接修复#

1. 从 vercel.json 删除 cleanUrls: true，HTML 文件保持原名，目录路由恢复正常；

2. 固定 Vercel CLI 版本到 57：

   1
   npx -y vercel@57 build --prod
   2
   npx -y vercel@57 deploy --prebuilt --prod

   vercel@57 同样会生成 l2s 分片，但采用硬链接（index.html 保持真实文件），上传到 Vercel 后数据完整。58.7.1 则会被坏符号链接“阉割”掉大文件。

3. CI workflow 中同步把 npx vercel 改为 npx vercel@57，防止自动升级到带 bug 的版本。