From ec8aadedb79db51fcc027a9d5aceea81ceff5a4d Mon Sep 17 00:00:00 2001 From: pyh Date: Wed, 30 Sep 2026 11:37:25 +0800 Subject: [PATCH] docs: record what the release workflow actually depends on The publish section now says why the workflow avoids external actions, that a repeated version is a skip rather than a failure, and that an npm registry line pointing elsewhere produces a misleading 'version already exists'. --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a60ef8f..8057c45 100644 --- a/README.md +++ b/README.md @@ -88,9 +88,10 @@ git tag -a v1.0.1 -m "v1.0.1" && git push origin v1.0.1 前提与排查： - 实例启用了 Actions 并注册了 runner（`runs-on: ubuntu-latest` 要与 runner 的标签一致）； +- 工作流**不使用任何 `uses:` 外部 action**：检出用 `git fetch`，Node/npm 用 runner 镜像自带的那份。这样 runner 不必访问 github.com（国内自建 runner 拉 `actions/checkout` 常超时，症状是所有步骤 `cancelled`，日志里是 `dial tcp …:443: i/o timeout`）。若你的镜像里没有 node，请换成带 node 的 runner 镜像； - 若组织把 Actions 令牌上限设成只读，或任务令牌对包命名空间没有写权限，发布步骤会很快失败：配置 `NPM_TOKEN` 即可，工作流会自动改用它； -- 已发布的版本会在发布前被检测到并**跳过**，所以手动重跑同一个版本是安全的（不会失败，也不再重复上传）； -- 真失败时看 `Publish` 步骤日志：`registry =` 那行确认注册表地址，`npm error code` 给出原因（`E401/E403` = 令牌无效或权限不足）。注意 Gitea 的 npm 注册表**不实现** `/-/whoami`，`npm whoami` 返回 404 属正常现象；`npm config get ...:_authToken` 也必然报 protected，因为 npm 禁止读回令牌。 +- 已发布的版本不会让工作流失败：注册表对同版本返回 409（`package version already exists`），npm 客户端也会用 `cannot publish over the previously published versions` 拦下，两种都记为“已存在，本次跳过”，所以手动重跑同一个版本是安全的； +- 真失败时看 `Publish` 步骤日志：`registry =` 那行确认注册表地址（必须是 `…/api/packages/dsh-plugin/npm/`，否则 npm 会拿 registry.npmjs.org 的判断结果说“版本已存在”），`npm error code` 给出原因（`E401/E403` = 令牌无效或权限不足）。注意 Gitea 的 npm 注册表**不实现** `/-/whoami`，`npm whoami` 返回 404 属正常现象；`npm config get ...:_authToken` 也必然报 protected，因为 npm 禁止读回令牌。 手工发布等价于：