在 #3197 的修复过程中顺手跑检查时发现,与那个 PR 无关,按 Prime Directive #10 单独记录。
现象
在未经修改的 origin/main(dd06bcd)上:
$ node scripts/check-doc-links.mjs; echo "exit: $?"
Found 1 broken docs link:
- content/docs/core/enhanced-actions.mdx -> /docs/components/form
exit: 1
链接确实是坏的:content/docs/components/form/ 是一个目录,里面是 button.mdx、input.mdx 等 20 来个文件,没有 index.md/index.mdx,所以 /docs/components/form 这条路由没有页面。
为什么一直没人发现
因为这个检查从来没有跑过。docs:check-links 只出现在 package.json 里:
$ grep -rn "check-doc-links\|docs:check-links" .github/ package.json turbo.json
package.json:41: "docs:check-links": "node scripts/check-doc-links.mjs",
.github/ 下零命中 —— 没有任何工作流调用它。
而另一个链接检查器 check-links.yml(Lychee)同样不拦 PR,它的触发条件是 workflow_dispatch:,底下的 push: / pull_request: 是被注释掉的:
on:
workflow_dispatch:
# push:
# branches:
# - main
# pull_request:
所以仓库里有两个链接检查器,一个能跑但没人跑,一个只能手动触发。这正是 #3197 那一类问题的同款形状:能力声明了,但没有被执行(Prime Directive #10 的推论)。
建议(需要维护者定方向,故未直接动手)
先修那条坏链接(要么给 content/docs/components/form/ 补一个索引页,要么把 enhanced-actions.mdx 里的链接改指到 /docs/components/form/form),然后二选一:
- A:把
node scripts/check-doc-links.mjs 加进 ci.yml 的 docs 任务 —— 它是纯本地文件系统检查,零网络、几十毫秒,加进去几乎不花时间,且天然稳定(不会因为外站挂了而 flaky)。
- B:把
check-links.yml 的 pull_request 触发放开 —— 覆盖面更大(含外链),但 Lychee 会打外部网络,PR 门禁上容易 flaky,通常需要配合 --exclude 和定时跑而不是 PR 跑。
我倾向 A 作为 PR 门禁 + B 保持定时/手动:内链断裂是我们自己造成的、必然可复现的,适合当硬门禁;外链断裂是别人造成的、随机的,适合定期巡检。但这是维护者的取舍,先记录不擅自决定。
在 #3197 的修复过程中顺手跑检查时发现,与那个 PR 无关,按 Prime Directive #10 单独记录。
现象
在未经修改的
origin/main(dd06bcd)上:链接确实是坏的:
content/docs/components/form/是一个目录,里面是button.mdx、input.mdx等 20 来个文件,没有index.md/index.mdx,所以/docs/components/form这条路由没有页面。为什么一直没人发现
因为这个检查从来没有跑过。
docs:check-links只出现在package.json里:.github/下零命中 —— 没有任何工作流调用它。而另一个链接检查器
check-links.yml(Lychee)同样不拦 PR,它的触发条件是workflow_dispatch:,底下的push:/pull_request:是被注释掉的:所以仓库里有两个链接检查器,一个能跑但没人跑,一个只能手动触发。这正是 #3197 那一类问题的同款形状:能力声明了,但没有被执行(Prime Directive #10 的推论)。
建议(需要维护者定方向,故未直接动手)
先修那条坏链接(要么给
content/docs/components/form/补一个索引页,要么把enhanced-actions.mdx里的链接改指到/docs/components/form/form),然后二选一:node scripts/check-doc-links.mjs加进ci.yml的docs任务 —— 它是纯本地文件系统检查,零网络、几十毫秒,加进去几乎不花时间,且天然稳定(不会因为外站挂了而 flaky)。check-links.yml的pull_request触发放开 —— 覆盖面更大(含外链),但 Lychee 会打外部网络,PR 门禁上容易 flaky,通常需要配合--exclude和定时跑而不是 PR 跑。我倾向 A 作为 PR 门禁 + B 保持定时/手动:内链断裂是我们自己造成的、必然可复现的,适合当硬门禁;外链断裂是别人造成的、随机的,适合定期巡检。但这是维护者的取舍,先记录不擅自决定。