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

本页面假设你已经:
- 初始化了
fern文件夹,为你的 TypeScript SDK 创建了 GitHub 仓库,并在generators.yml中配置了 TypeScript 生成器组。请参考生成 SDK (TypeScript)。
配置 SDK 包设置
你需要更新 generators.yml 文件来配置包名、输出位置和客户端命名,以便进行 npm 发布。你的 generators.yml 应该位于你的源仓库中(或在你的本地机器上),而不是包含你的 TypeScript SDK 代码的仓库中。
配置 GitHub 发布
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 main, 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 release
You 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 的发布(也称为”可信发布”)是最安全的发布方式。使用 OIDC,你不需要管理身份验证令牌 - npmjs 信任你的 GitHub 仓库直接发布。
前提条件
- Fern TypeScript SDK 生成器版本
3.12.3或更高 - Fern CLI 版本
0.94.0或更高(仅在使用--local本地生成时需要)
生成你的 SDK
生成你的 SDK 以创建带有 OIDC 配置的 GitHub Actions 工作流:
这会创建一个配置为使用 OIDC 进行 npmjs 发布的 .github/workflows/ci.yml 文件。或者,你可以推送 generators.yml 更改并让 Fern GitHub Action 为你生成工作流。
这会创建一个配置为使用 OIDC 进行 npm 发布的 .github/workflows/ci.yml 文件。
在 npmjs.com 上授权你的仓库
在 npmjs.com 上配置可信发布,允许你的 GitHub 仓库进行发布:
- 导航到你在 npmjs.com 上的包设置
- 找到 Trusted Publisher 部分并点击 Add trusted publisher
- 选择 GitHub Actions 作为提供者
- 填写:
- Organization or user:你的 GitHub 用户名或组织
- Repository:你的 TypeScript SDK 仓库名称(例如,
your-org/your-repository) - Workflow filename:
ci.yml - Environment name:留空
更多详情,请参考 npm 的可信发布文档。
故障排除
“无法认证”错误
常见原因:
- 工作流文件名不完全匹配(必须是
ci.yml) - npmjs.com 上的可信发布者配置与你的仓库设置不匹配
- 使用自托管运行器(npmjs.org 不支持)
解决方案:仔细检查你在 npmjs.com 上的可信发布者配置是否与你的仓库名称和工作流文件名完全匹配。
私有仓库限制
即使使用可信发布,从私有仓库发布的包也不会生成溯源证明。这是一个已知限制。
基于令牌的身份验证(遗留)
npm 已弃用长期有效的经典令牌。 长期有效的身份验证令牌可能在日志中暴露、被泄露,并且难以管理和轮换。强烈推荐使用基于 OIDC 的身份验证。
发布你的 SDK
当你创建带有版本标签的 GitHub 发布时,你的 SDK 将自动发布到 npmjs:
- 创建带有版本标签的 GitHub 发布(例如,
v1.0.0) - CI 工作流将自动运行并发布到 npm
- 在 npmjs.com 上查看你的包以确认版本
替代方案:手动工作流调度
如果你更喜欢手动触发发布,创建一个 .github/workflows/publish.yml 文件:
添加你的 FERN_TOKEN 作为仓库秘密(运行 fern token 生成一个),然后从 Actions 标签页触发工作流。
从基于令牌的身份验证迁移到 OIDC 发布
如果你正在使用基于令牌的身份验证并需要迁移到 OIDC,请按照以下步骤操作:
为什么迁移到 OIDC
npmjs 正在实施可信发布来消除与长期有效令牌相关的安全风险,这些令牌可能:
- 在日志或配置文件中暴露
- 被泄露并持续使用,直到手动撤销
- 难以管理和轮换
基于 OIDC 的发布使用短期有效的、加密签名的令牌,这些令牌特定于你的工作流,不能被提取或重复使用。
前提条件
在迁移之前,确保你有:
- 发布到 npmjs.org 的包
- 配置了 GitHub Actions 的 GitHub 仓库
- 访问你在 npmjs.com 上的包设置的权限
- Fern CLI 版本
0.94.0或更高(用于本地生成)
选择你的迁移路径
选择适合你情况的方法:
路径 1:升级你的生成器(推荐)
如果你可以升级到 TypeScript SDK 生成器版本 3.12.3 或更高,这是最简单的路径。
何时使用此路径:
- 你能够升级到 Fern TypeScript SDK 生成器版本 3.12.3 或更高
- 你没有在
.fernignore中忽略你的 CI 工作流文件
在 npmjs.com 上配置可信发布
按照 npm 的”在 npmjs.com 上添加可信发布者”说明:
- 导航到你在 npmjs.com 上的包设置
- 找到 Trusted Publisher 部分并点击 Add trusted publisher
- 选择 GitHub Actions 作为提供者
- 配置:
- Organization or user:你的 GitHub 用户名或组织
- Repository:你的 TypeScript SDK 仓库名称
- Workflow filename:
ci.yml(默认的 Fern 工作流文件) - Environment name:留空(除非你使用 GitHub 环境)
路径 2:手动 CI 工作流更新
如果你无法升级生成器或自定义了 CI 工作流,请使用此路径。
何时使用此路径:
- 由于破坏性更改或错误而无法升级
- 你已自定义 CI 工作流并将其添加到
.fernignore - 路径 1 未更新你的工作流文件
验证你的迁移
完成任一迁移路径后:
- 触发工作流运行,通过创建带有 alpha 标签的 GitHub 发布(例如,
v1.0.0-alpha) - 检查工作流日志以验证发布步骤成功
- 验证溯源,访问你在 npmjs.com 上的包 - 你应该看到一个溯源徽章
迁移故障排除
"无法认证"错误
常见原因:
- 工作流文件名不完全匹配(必须是带有
.yml扩展名的ci.yml) - 工作流中缺少
id-token: write或contents: read权限 - npm CLI 版本低于 11.5.1
- 使用自托管运行器(不支持)
解决方案: 仔细检查你在 npmjs.com 上的可信发布者配置是否与你的实际工作流文件名匹配,并验证所有要求是否满足。
工作流仍在使用 NPM_TOKEN
如果你的工作流继续使用基于令牌的身份验证:
- 验证你已从发布步骤中删除了
npm config set行和env: NPM_TOKEN块 - 检查 npm CLI 版本 11.5.1+ 是否已安装(添加更新 npm 步骤)
- 确保你使用的是生成器版本 3.12.3 或更高(如果使用路径 1)
- 使用
--local生成时,你需要使用 Fern CLI 版本 0.94.0 或更高