Skip to content

docs: 未知非 ASCII 路径在 Vercel 上 500(x-next-cache-tags 头崩溃),应为干净 404 #370

Description

@longsizhuo

现象

Sentry INVOLUTIONHELL-FRONTEND-4TypeError: Invalid character in header content ["x-next-cache-tags"],197 次(2026-05-07 起持续),transaction GET /[locale]/docs/[...slug],全部来自爬虫访问不存在的中文路径,例如:

/zh/docs/learn/cs/dev-tips/你的图片.jpg "自定义鼠标悬停显示名"

(AhrefsBot 把 CommonUsedMarkdown.md:72 反引号里的示例代码当链接爬了,内容本身没问题。)

根因

未知 slug 不在 generateStaticParams 里 → 走运行时动态渲染(legacy resolve 重定向流程)→ Vercel 的 Next 运行时把含原始中文的 cache tag(_N_T_/zh/docs/...)写进 x-next-cache-tags 响应头 → Node http 拒绝非 ISO-8859-1 header 值 → 未捕获 TypeError → 500。

正常中文文档页不受影响(SSG 预渲染,由 CDN 直接回,不经过运行时 header 写入)。只有"不存在的非 ASCII 路径"会 500 而不是 404。

上游状态

框架层 bug:vercel/next.js#92145(closed:missing repro,未修)、#93140、#93142 同类。next 16.2.6 → 16.2.10 changelog 无对应修复,升级无效。

可选修复方向

  1. 推上游:提最小复现(dynamic route + generateStaticParams + revalidate + 非 ASCII param on Vercel),引用 #92145。
  2. dynamicParams = false + 把 legacy resolve 逻辑挪进 not-found 边界。需验证两点:not-found 渲染是否还 emit 该 header;next build 输出 diff 确认所有 docs 仍是 SSG(见 frontend/CLAUDE.md 的验证流程)。
  3. proxy.ts 短路(治标):对解码后含非 ISO-8859-1 且明显非法(引号、空格、图片扩展名)的 docs 路径直接 404。会漏掉"正常中文旧路径需要 resolve 重定向"的场景。

影响

真人用户基本无感(触发者全是爬虫),主要是 SEO(对爬虫回 500 不友好)+ Sentry 噪音。不紧急,但值得修。

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions