发布到 npm
发布到 npm
发布到 npm
将你的面向公众的 Fern TypeScript SDK 发布到 npmjs registry。按照本页面的步骤操作后,你将在 npm 上发布一个有版本号的包。
如果你正在使用基于令牌的身份验证,npm 已弃用长期有效的经典令牌。请查看从基于令牌的身份验证迁移到 OpenID Connect (OIDC) 发布以升级到更安全的 OIDC 身份验证。

本页面假设你已经:
fern 文件夹,为你的 TypeScript SDK 创建了 GitHub 仓库,并在 generators.yml 中配置了 TypeScript 生成器组。请参考生成 SDK (TypeScript)。你需要更新 generators.yml 文件来配置包名、输出位置和客户端命名,以便进行 npm 发布。你的 generators.yml 应该位于你的源仓库中(或在你的本地机器上),而不是包含你的 TypeScript SDK 代码的仓库中。
Fern 可以通过 GitHub Actions 自动将你的 SDK 发布到 npmjs。配置你的 GitHub 仓库和发布模式:
Optionally set the mode to control how Fern handles SDK publishing:
mode: release (default): Fern generates code, commits to the default branch (or the branch you specify), and tags a release automaticallymode: pull-request (recommended): Fern generates code and creates a PR for you to review before releasemode: push: Fern generates code and pushes to a branch you specify for you to review before releaseYou can also configure other settings, like the reviewers or license. Refer to the full github (generators.yml) reference for more information.
选择你想要在发布时如何与 npmjs 进行身份验证。
npm 已弃用长期有效的经典令牌用于从 CI/CD 工作流发布。强烈推荐使用 OpenID Connect (OIDC) 身份验证以保证安全。
基于 OIDC 的发布(也称为”可信发布”)是最安全的发布方式。使用 OIDC,你不需要管理身份验证令牌 - npmjs 信任你的 GitHub 仓库直接发布。
3.12.3 或更高0.94.0 或更高(仅在使用 --local 本地生成时需要)生成你的 SDK 以创建带有 OIDC 配置的 GitHub Actions 工作流:
这会创建一个配置为使用 OIDC 进行 npmjs 发布的 .github/workflows/ci.yml 文件。或者,你可以推送 generators.yml 更改并让 Fern GitHub Action 为你生成工作流。
这会创建一个配置为使用 OIDC 进行 npm 发布的 .github/workflows/ci.yml 文件。
在 npmjs.com 上配置可信发布,允许你的 GitHub 仓库进行发布:
your-org/your-repository)ci.yml更多详情,请参考 npm 的可信发布文档。
“无法认证”错误
常见原因:
ci.yml)解决方案:仔细检查你在 npmjs.com 上的可信发布者配置是否与你的仓库名称和工作流文件名完全匹配。
私有仓库限制
即使使用可信发布,从私有仓库发布的包也不会生成溯源证明。这是一个已知限制。
npm 已弃用长期有效的经典令牌。 长期有效的身份验证令牌可能在日志中暴露、被泄露,并且难以管理和轮换。强烈推荐使用基于 OIDC 的身份验证。
当你创建带有版本标签的 GitHub 发布时,你的 SDK 将自动发布到 npmjs:
v1.0.0)如果你更喜欢手动触发发布,创建一个 .github/workflows/publish.yml 文件:
添加你的 FERN_TOKEN 作为仓库秘密(运行 fern token 生成一个),然后从 Actions 标签页触发工作流。
如果你正在使用基于令牌的身份验证并需要迁移到 OIDC,请按照以下步骤操作:
npmjs 正在实施可信发布来消除与长期有效令牌相关的安全风险,这些令牌可能:
基于 OIDC 的发布使用短期有效的、加密签名的令牌,这些令牌特定于你的工作流,不能被提取或重复使用。
在迁移之前,确保你有:
0.94.0 或更高(用于本地生成)选择适合你情况的方法:
如果你可以升级到 TypeScript SDK 生成器版本 3.12.3 或更高,这是最简单的路径。
何时使用此路径:
.fernignore 中忽略你的 CI 工作流文件按照 npm 的”在 npmjs.com 上添加可信发布者”说明:
ci.yml(默认的 Fern 工作流文件)如果你无法升级生成器或自定义了 CI 工作流,请使用此路径。
何时使用此路径:
.fernignore完成任一迁移路径后:
v1.0.0-alpha)常见原因:
.yml 扩展名的 ci.yml)id-token: write 或 contents: read 权限解决方案: 仔细检查你在 npmjs.com 上的可信发布者配置是否与你的实际工作流文件名匹配,并验证所有要求是否满足。
如果你的工作流继续使用基于令牌的身份验证:
npm config set 行和 env: NPM_TOKEN 块--local 生成时,你需要使用 Fern CLI 版本 0.94.0 或更高