发布到 npm

以 Markdown 格式查看

将你的面向公众的 Fern TypeScript SDK 发布到 npmjs registry。按照本页面的步骤操作后,你将在 npm 上发布一个有版本号的包。

已经在发布到 npm?

如果你正在使用基于令牌的身份验证,npm 已弃用长期有效的经典令牌。请查看从基于令牌的身份验证迁移到 OpenID Connect (OIDC) 发布以升级到更安全的 OIDC 身份验证。

在 npmjs.com 上发布的有版本号的包

本页面假设你已经:

  • 初始化了 fern 文件夹,为你的 TypeScript SDK 创建了 GitHub 仓库,并在 generators.yml 中配置了 TypeScript 生成器组。请参考生成 SDK (TypeScript)

配置 SDK 包设置

你需要更新 generators.yml 文件来配置包名、输出位置和客户端命名,以便进行 npm 发布。你的 generators.yml 应该位于你的源仓库中(或在你的本地机器上),而不是包含你的 TypeScript SDK 代码的仓库中。

1

配置 output 位置

在你的 TypeScript SDK 的 group 中,将输出位置从 local-file-system(默认值)更改为 npm,以指示 Fern 应该直接将你的包发布到 npmjs registry:

generators.yml
1groups:
2 ts-sdk: # 你的 TypeScript SDK 的组名
3 generators:
4 - name: fernapi/fern-typescript-sdk
5 version: 3.69.0
6 output:
7 location: npm
2

添加唯一的包名

你的包名必须在 npmjs registry 中是唯一的,否则发布你的 SDK 将会失败。

generators.yml
1groups:
2 ts-sdk:
3 generators:
4 - name: fernapi/fern-typescript-sdk
5 version: 3.69.0
6 output:
7 location: npm
8 package-name: your-package-name
3

配置 namespaceExport

namespaceExport 选项控制生成的客户端的名称。这是客户使用的名称来导入你的 SDK(import { your-client-name } from 'your-package-name';)。

generators.yml
1groups:
2 ts-sdk:
3 generators:
4 - name: fernapi/fern-typescript-sdk
5 version: 3.69.0
6 output:
7 location: npm
8 package-name: your-package-name
9 config:
10 namespaceExport: YourClientName # 必须是 PascalCase

配置 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 automatically
  • mode: pull-request (recommended): Fern generates code and creates a PR for you to review before release
  • mode: 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.

generators.yml
1groups:
2 ts-sdk:
3 generators:
4 - name: fernapi/fern-typescript-sdk
5 version: 3.69.0
6 output:
7 location: npm
8 package-name: your-package-name
9 config:
10 namespaceExport: YourClientName
11 github:
12 repository: your-org/your-repository
13 mode: push # 或 "pull-request"
14 branch: your-branch-name # mode: push 时必需

配置身份验证

选择你想要在发布时如何与 npmjs 进行身份验证。

npm 已弃用长期有效的经典令牌用于从 CI/CD 工作流发布。强烈推荐使用 OpenID Connect (OIDC) 身份验证以保证安全。

OIDC 身份验证(推荐)

基于 OIDC 的发布(也称为”可信发布”)是最安全的发布方式。使用 OIDC,你不需要管理身份验证令牌 - npmjs 信任你的 GitHub 仓库直接发布。

前提条件
  • Fern TypeScript SDK 生成器版本 3.12.3 或更高
  • Fern CLI 版本 0.94.0 或更高(仅在使用 --local 本地生成时需要)
1

在 generators.yml 中添加 OIDC

output 部分添加 token: OIDC

generators.yml
1groups:
2 ts-sdk:
3 generators:
4 - name: fernapi/fern-typescript-sdk
5 version: 3.69.0 # 必须是 3.12.3 或更高
6 output:
7 location: npm
8 package-name: your-package-name
9 token: OIDC
10 config:
11 namespaceExport: YourClientName
12 github:
13 repository: your-org/your-repository
14 mode: push
15 branch: your-branch-name
2

生成你的 SDK

生成你的 SDK 以创建带有 OIDC 配置的 GitHub Actions 工作流:

$fern generate --group ts-sdk

这会创建一个配置为使用 OIDC 进行 npmjs 发布的 .github/workflows/ci.yml 文件。或者,你可以推送 generators.yml 更改并让 Fern GitHub Action 为你生成工作流。

这会创建一个配置为使用 OIDC 进行 npm 发布的 .github/workflows/ci.yml 文件。

3

在 npmjs.com 上授权你的仓库

在 npmjs.com 上配置可信发布,允许你的 GitHub 仓库进行发布:

  1. 导航到你在 npmjs.com 上的包设置
  2. 找到 Trusted Publisher 部分并点击 Add trusted publisher
  3. 选择 GitHub Actions 作为提供者
  4. 填写:
    • Organization or user:你的 GitHub 用户名或组织
    • Repository:你的 TypeScript SDK 仓库名称(例如,your-org/your-repository
    • Workflow filenameci.yml
    • Environment name:留空

更多详情,请参考 npm 的可信发布文档

“无法认证”错误

常见原因:

  • 工作流文件名不完全匹配(必须是 ci.yml
  • npmjs.com 上的可信发布者配置与你的仓库设置不匹配
  • 使用自托管运行器(npmjs.org 不支持)

解决方案:仔细检查你在 npmjs.com 上的可信发布者配置是否与你的仓库名称和工作流文件名完全匹配。

私有仓库限制

即使使用可信发布,从私有仓库发布的包也不会生成溯源证明。这是一个已知限制

npm 已弃用长期有效的经典令牌。 长期有效的身份验证令牌可能在日志中暴露、被泄露,并且难以管理和轮换。强烈推荐使用基于 OIDC 的身份验证

1

生成 npm 令牌

  1. 登录 npmjs.com
  2. 点击你的头像并选择 Edit Profile
  3. 选择 Access Tokens
  4. 点击 Generate New Token 并选择 Classic Token(选择”Automation”类型)或 Granular Access Token
  5. 安全保存你的令牌 - 它不会再次显示
有关访问令牌的更多信息,请参考 npm 的关于访问令牌文档。
2

在 generators.yml 中添加令牌

output 部分添加 token: ${NPM_TOKEN}

generators.yml
1groups:
2 ts-sdk:
3 generators:
4 - name: fernapi/fern-typescript-sdk
5 version: 3.69.0
6 output:
7 location: npm
8 package-name: your-package-name
9 token: ${NPM_TOKEN}
10 config:
11 namespaceExport: YourClientName
12 github:
13 repository: your-org/your-repository
14 mode: push
15 branch: your-branch-name
3

将 NPM_TOKEN 添加为 GitHub Actions 秘密

  1. 在 GitHub 上打开你的仓库并转到 Settings
  2. 导航到 Secrets and variables > Actions
  3. 点击 New repository secret
  4. 命名为 NPM_TOKEN 并粘贴你的 npm 令牌
  5. 点击 Add secret

发布你的 SDK

当你创建带有版本标签的 GitHub 发布时,你的 SDK 将自动发布到 npmjs:

  1. 创建带有版本标签的 GitHub 发布(例如,v1.0.0
  2. CI 工作流将自动运行并发布到 npm
  3. 在 npmjs.com 上查看你的包以确认版本

如果你更喜欢手动触发发布,创建一个 .github/workflows/publish.yml 文件:

.github/workflows/publish.yml
1name: Publish TypeScript SDK
2
3on:
4 workflow_dispatch:
5 inputs:
6 version:
7 description: "Version to publish (e.g., 1.0.0)"
8 required: true
9 type: string
10
11jobs:
12 publish:
13 runs-on: ubuntu-latest
14 steps:
15 - name: Checkout repo
16 uses: actions/checkout@v4
17
18 - name: Install Fern
19 run: npm install -g fern-api
20
21 - name: Generate and publish SDK
22 env:
23 FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
24 run: fern generate --group ts-sdk --version ${{ inputs.version }} --log-level debug

添加你的 FERN_TOKEN 作为仓库秘密(运行 fern token 生成一个),然后从 Actions 标签页触发工作流。


从基于令牌的身份验证迁移到 OIDC 发布

如果你正在使用基于令牌的身份验证并需要迁移到 OIDC,请按照以下步骤操作:

为什么迁移到 OIDC

npmjs 正在实施可信发布来消除与长期有效令牌相关的安全风险,这些令牌可能:

  • 在日志或配置文件中暴露
  • 被泄露并持续使用,直到手动撤销
  • 难以管理和轮换

基于 OIDC 的发布使用短期有效的、加密签名的令牌,这些令牌特定于你的工作流,不能被提取或重复使用。

前提条件

在迁移之前,确保你有:

  • 发布到 npmjs.org 的包
  • 配置了 GitHub Actions 的 GitHub 仓库
  • 访问你在 npmjs.com 上的包设置的权限
  • Fern CLI 版本 0.94.0 或更高(用于本地生成)

选择你的迁移路径

选择适合你情况的方法:

如果你可以升级到 TypeScript SDK 生成器版本 3.12.3 或更高,这是最简单的路径。

何时使用此路径:

  • 你能够升级到 Fern TypeScript SDK 生成器版本 3.12.3 或更高
  • 你没有在 .fernignore 中忽略你的 CI 工作流文件
1

在 npmjs.com 上配置可信发布

按照 npm 的”在 npmjs.com 上添加可信发布者”说明:

  1. 导航到你在 npmjs.com 上的包设置
  2. 找到 Trusted Publisher 部分并点击 Add trusted publisher
  3. 选择 GitHub Actions 作为提供者
  4. 配置:
    • Organization or user:你的 GitHub 用户名或组织
    • Repository:你的 TypeScript SDK 仓库名称
    • Workflow filenameci.yml(默认的 Fern 工作流文件)
    • Environment name:留空(除非你使用 GitHub 环境)
2

更新你的 generators.yml

output.token 字段从 ${NPM_TOKEN} 更改为 OIDC,并确保你使用版本 3.12.3 或更高:

generators.yml
1groups:
2 ts-sdk:
3 generators:
4 - name: fernapi/fern-typescript-sdk
5 version: 3.69.0 # 必须是 3.12.3 或更高
6 output:
7 location: npm
8 package-name: your-package-name
9 token: OIDC # 从 ${NPM_TOKEN} 更改
10 config:
11 namespaceExport: YourClientName
12 github:
13 repository: your-org/your-repository
3

重新生成你的 SDK

使用更新的 CI 配置重新生成你的 SDK。你可以:

本地:

$fern generate --group ts-sdk

或通过 GitHub Actions:

如果你使用 Fern GitHub Action 生成 SDK,只需推送更新的 generators.yml 文件,让工作流为你重新生成 SDK。

这将使用所需的 OIDC 权限更新你的 .github/workflows/ci.yml 文件。

4

删除 NPM_TOKEN 秘密

在验证迁移工作后,从你的 GitHub 仓库设置中删除 NPM_TOKEN 秘密以防止意外使用。

如果你无法升级生成器或自定义了 CI 工作流,请使用此路径。

何时使用此路径:

  • 由于破坏性更改或错误而无法升级
  • 你已自定义 CI 工作流并将其添加到 .fernignore
  • 路径 1 未更新你的工作流文件
1

在 npmjs.com 上配置可信发布

按照路径 1 的相同说明在 npmjs.com 上将你的仓库添加为可信发布者。

2

手动更新你的 CI 工作流

打开你的 .github/workflows/ci.yml 文件并对 publish 作业进行以下更改:

.github/workflows/ci.yml
1publish:
2 needs: [ compile, test ]
3 if: github.event_name == 'push' && contains(github.ref, 'refs/tags/')
4 runs-on: ubuntu-latest
5 permissions:
6 contents: read # 添加此项:actions/checkout@v4 必需
7 id-token: write # 添加此项:OIDC 必需
8 steps:
9 - name: Checkout repo
10 uses: actions/checkout@v4
11
12 - name: Set up node
13 uses: actions/setup-node@v4
14
15 # 添加此项:确保安装 npm 11.5.1 或更高版本以支持 OIDC
16 - name: Update npm
17 run: npm install -g npm@latest
18
19 - name: Install pnpm
20 uses: pnpm/action-setup@v4
21
22 - name: Install dependencies
23 run: pnpm install
24
25 - name: Build
26 run: pnpm build
27
28 # 修改此项:删除 npm config set 和 env 块
29 - name: Publish to npm
30 run: |
31 if [[ ${GITHUB_REF} == *alpha* ]]; then
32 npm publish --access public --tag alpha
33 elif [[ ${GITHUB_REF} == *beta* ]]; then
34 npm publish --access public --tag beta
35 else
36 npm publish --access public
37 fi
38 # 之前有:
39 # run: |
40 # npm config set //registry.npmjs.org/:_authToken ${NPM_TOKEN}
41 # if [[ ${GITHUB_REF} == *alpha* ]]; then
42 # npm publish --access public --tag alpha
43 # elif [[ ${GITHUB_REF} == *beta* ]]; then
44 # npm publish --access public --tag beta
45 # else
46 # npm publish --access public
47 # fi
48 # env:
49 # NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

关键更改:

  • 在 publish 作业中添加带有 id-token: writecontents: readpermissions
  • 添加步骤来更新 npm 到版本 11.5.1 或更高
  • 从 publish 步骤中删除 npm config set
  • 从 publish 步骤中删除带有 NPM_TOKENenv
3

(可选)将 ci.yml 添加到 .fernignore

如果你还没有,将你的 CI 工作流添加到 .fernignore 以防止未来的生成器更新覆盖你的手动更改:

.fernignore
.github/workflows/ci.yml
4

删除 NPM_TOKEN 秘密

在验证迁移工作后,从你的 GitHub 仓库设置中删除 NPM_TOKEN 秘密。

验证你的迁移

完成任一迁移路径后:

  1. 触发工作流运行,通过创建带有 alpha 标签的 GitHub 发布(例如,v1.0.0-alpha
  2. 检查工作流日志以验证发布步骤成功
  3. 验证溯源,访问你在 npmjs.com 上的包 - 你应该看到一个溯源徽章

迁移故障排除

常见原因:

  • 工作流文件名不完全匹配(必须是带有 .yml 扩展名的 ci.yml
  • 工作流中缺少 id-token: writecontents: read 权限
  • npm CLI 版本低于 11.5.1
  • 使用自托管运行器(不支持)

解决方案: 仔细检查你在 npmjs.com 上的可信发布者配置是否与你的实际工作流文件名匹配,并验证所有要求是否满足。

如果你的工作流继续使用基于令牌的身份验证:

  • 验证你已从发布步骤中删除了 npm config set 行和 env: NPM_TOKEN
  • 检查 npm CLI 版本 11.5.1+ 是否已安装(添加更新 npm 步骤)
  • 确保你使用的是生成器版本 3.12.3 或更高(如果使用路径 1)
  • 使用 --local 生成时,你需要使用 Fern CLI 版本 0.94.0 或更高