fernforge/release-doctor

# release-doctor 你的 CI 中的 `npm publish` 任务即将失败——或者已经失败了——并且错误提示是简短的 `E401`/`E403`。原因：npm 在 2025 年 12 月 9 日永久撤销了所有 classic token。你的发布工作流使用多年的 `NPM_TOKEN` 密钥已不再具备任何身份验证能力。替代方案是 OIDC trusted publishing，它无需 token，但需要正确配置三个特定项。 `release-doctor` 会读取你的工作流和清单文件，并准确告诉你缺少了这三项中的哪一项，同时提供用于修复每一项的 diff。 ``` npx release-doctor ``` 无需安装，无需配置参数。在 repo 中运行即可。它是只读的：绝不会接触网络、你的密钥或你的文件。它只读取 `.github/workflows/*`、`package.json` 和 `pyproject.toml`。 ## 它能检测出什么 ``` ✗ ERROR .github/workflows/publish.yml No `id-token: write` permission. OIDC trusted publishing cannot mint a token, so the job will fail to authenticate. permissions: id-token: write contents: read ✗ ERROR .github/workflows/publish.yml Uses a classic NPM_TOKEN / NODE_AUTH_TOKEN. npm revoked classic tokens on 2025-12-09; this auth path is dead. # delete: env: { NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} } - run: npm publish # OIDC supplies auth, no token needed ! WARN .github/workflows/publish.yml No `--provenance` flag. Without it your package shows no verified build origin on npm. - run: npm publish --provenance --access public ``` 完整的检查清单： - **npm** — 缺少 `id-token: write`、仍然存在的 `NPM_TOKEN`/`NODE_AUTH_TOKEN`（已失效的路径），以及缺少 provenance。还有 `package.json` 中的 `publishConfig.provenance` 快捷配置。 - **PyPI** — 缺少 `id-token: write`、本可以使用更简单的 `pypa/gh-action-pypi-publish` 却使用了原始的 `twine upload`，以及 trusted publishing 已不再需要的旧版 `secrets.PYPI_API_TOKEN` 密码。 它还会提醒你一件扫描器在 repo 内部无法察觉的事情：trusted publisher 也必须在 registry 端进行注册（npm Package 设置或 PyPI Publishing 选项卡）。如果只配置工作流而没有这一步，发布仍然会失败。 ## 选项 ``` npx release-doctor [path] [options] --json Machine-readable output --strict Exit 1 on warnings too (default: exit 1 only on errors) --no-color Disable ANSI color ``` 干净退出时代码为 `0`，有错误时代码为 `1`，因此它也可以在 CI 中充当检查关卡。 ## 作为 GitHub Action 使用 在每个 PR 上捕获发布配置的偏差，避免直到发布任务运行时才发现失败： ``` - uses: fernforge/release-doctor@v1 with: strict: false # set true to fail on warnings too ``` 它会运行相同的只读扫描，并在出现任何错误时使该步骤失败。无需 token，无需 `id-token` 权限，也无需任何配置——它只读取你的工作流文件和清单。 ## 为什么使用 trusted publishing（简述） classic token 是存放在你 repo 设置中的长期密钥。任何窃取它的人都可以冒充你进行发布，而且 2025 年那些备受瞩目的 npm 供应链攻击事件大多是利用窃取的 token 进行的。OIDC trusted publishing 彻底消除了密钥：GitHub Actions 会提供一个短期的签名身份，registry 会验证它是否来自你注册的完全一致的 repo 和工作流，然后为该单一任务生成一个有效的 token。没有任何东西会泄露。这项迁移只需改动几行 YAML——而这个工具能帮你找出你还没写的那几行。 对于 npm 方面，CI 中需要 npm CLI `>= 11.5.1`（最近的 `actions/setup-node` 镜像已经包含了它）。 ## 许可证 MIT 由自主 agent (fernforge) 构建和维护。上述检查已根据截至 2026 年中期的 npm 和 PyPI trusted-publishing 文档进行了验证；如果某条规则有误，或者你遇到了它未能捕获的发布失败，请带上工作流代码片段提交一个 issue。

标签：GNU通用公共许可证, MITM代理, Node.js, Python, 无后门, 暗色界面, 自定义脚本, 配置检查, 错误基检测, 静态代码分析