KLucenの启示录

一、路径别名只在本地成立#

现象：本地所有测试全绿，线上函数加载失败。

1
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@shared/pageSchemas'
2
imported from /var/task/server/pageConfig.js

@shared/* 是 tsconfig 里的 paths 别名。本地 tsx 会解析它，Vercel 构建函数时不读 paths。同一个 import，本地是绿的，线上是死的。

修法有两层：改回相对路径；再给构建加一道闸门——从真实入口出发静态遍历 import 图，禁掉路径别名、前端代码和未声明的依赖，并接进 pnpm build。这类问题从此在构建阶段就以人话报出来。

二、配置缺失不该让整个函数无法启动#

现象：部署完成后打开页面，只看到一行 Unexpected token 'A', "A server e"...。

原因是漏了一个环境变量：程序按本地模式启动，在模块加载期去检查内容仓目录是否存在（Serverless 上当然不存在），抛异常，函数加载失败，平台返回一张纯文本错误页，前端的 response.json() 只好抛解析错误。整条报错和真正的原因毫无关系。

修法：内容仓路径解析不再抛异常；配置问题集中到 /api/health 的 problems 里；再加一个 env 清单，只报每个变量是 set 还是 missing，不回显值。现在同样的坏配置会直接说清楚：

1
{
2
  "mode": "local",
3
  "problems": [
4
    "本地模式，但内容仓不存在：/var/shirone-content\n如果这是部署到 Serverless（Vercel / Cloudflare），几乎一定是漏配了环境变量：\n  SHIRONE_STORAGE=github\n配好后需要重新部署（Redeploy）才会生效。"
5
  ]
6
}

三、重写规则的捕获名撞上了业务参数#

现象：文章列表正常，点开任意一篇报 文件不存在：doc。

错误里的路径就是字面的 doc——那是路由段。原因是 Vercel 的重写规则捕获名和业务查询参数重名：

1
{ "source": "/api/:path*", "destination": "/api/index?__path=:path*" }

平台除了应用目标里的查询参数，还会把匹配到的捕获段按捕获名注入成查询参数。于是 /api/doc?path=真实路径 变成「带 path=doc 的请求」，真实路径被覆盖，服务端就去内容仓里找一个叫 doc 的文件。列表接口没有 path 参数，所以只有点文章会坏。

修法：捕获名换成不会与业务参数重名的 __route，还原时把所有 __ 前缀参数当作桥接参数删掉。另外加了一个 /api/_bridge，把函数真实收到的 URL 原样吐出来。

四、「本地很快」的并发策略，在网络上会变成限流#

仪表盘要对每篇文章读一次 frontmatter。本地文件系统上 Promise.all 一把梭最快；换成网络请求之后，文章数就等于并发数——60 篇文章就是 60 个并发请求。

GitHub 除了明面上的小时额度，还有一层针对并发突发的次级速率限制（secondary rate limit），触发后返回 403，而且不计入小时额度。线上的症状就是「仪表盘转圈然后报错」。

修法：所有 GitHub 请求过一个并发闸门（默认 8），并识别次级限流、按 retry-after 重试。实测 60 篇文章、人为加 12ms 延迟：

五、workerd 里 import.meta.url 不是合法 URL#

现象：Cloudflare Workers 本地启动直接退出，只留一行 Uncaught TypeError: Invalid URL string，指向打包产物的某一行，完全看不出是哪段源码。

原因是 new URL("..", import.meta.url) 在模块加载期执行，而 workerd 里 import.meta.url 形如 worker.js，不是合法的绝对 URL。

修法：包一层 try/catch 兜底（那个路径在远程模式下本来也用不到）。

六、抽象泄漏：虚拟路径跑进了真实的 fs 调用#

删除一篇文章之后会自底向上清理空目录，用的是 rmdir。而远程模式下 resolveInRepo() 返回的是 /content/posts 这样的虚拟路径——把它交给真实的 rmdir，等于「去删文件系统根目录下的同名目录」。

它当时没出事，是因为 ENOENT 被 catch 兜住了。运气，不是设计。修法是让目录清理只在本地模式执行：git 的树是扁平的路径集合，本来就没有「空目录」这回事。