将库发布到 npm – 教程
使用 npm-publish Gradle 插件将你的 Kotlin Multiplatform 库手动或通过 GitHub Actions 发布到 npm。
要发布你的库,你需要:
- 准备凭据,包括 npm 帐户 和访问令牌。
- 在你的 Kotlin Multiplatform 项目中配置发布插件。
- 为发布插件提供凭据,或为持续集成设置 Trusted Publisher。
- 手动或使用 CI 运行发布任务。
在本教程中,我们使用 GitHub 托管项目,并通过 GitHub Actions 运行 CI。
示例库
你可以使用示例库项目跟进操作,并查看可正常运行的配置。
如果复用该代码,请务必将所有示例值替换为你项目的特定值。
准备帐户与凭据
要发布到 npm,你需要登录 npm 门户。
在本教程中,你需要一个组织和一个访问令牌来配置手动发布。
创建一个简易组织
在本教程中,我们在 npm 组织下发布库,以避免命名冲突。
要创建新组织,请遵循 npm 文档。
生成访问令牌
要手动发布到 npm,你需要一个允许在刚创建的组织下发布软件包的访问令牌。 要生成此类令牌,请遵循 npm 指南。
对于本教程,请使用简化的安全配置:
- 启用 Bypass two-factor authentication (2FA) 选项。
- 将令牌的常规权限和组织权限均设置为 Read and write。
配置库项目
如果你使用示例项目, 请在发布前更新默认名称。 这包括:
- 库模块的名称。
- 在
settings.gradle.kts文件中设置的项目名称。
名称设置完毕后,请按照以下步骤设置发布。
设置发布插件
本教程使用官方 npm-publish 插件来辅助发布到 npm。 要详细了解该插件及可用的配置选项,请参阅插件文档。
将该插件添加到你的 Kotlin Multiplatform 项目中:
打开库模块的
build.gradle.kts文件。在
plugins {}代码块中添加以下内容:kotlin// <module directory>/build.gradle.kts plugins { kotlin("npm-publish") version "3.7.0" }如需获取该插件的最新可用版本,请查看 Releases 页面。
添加以下配置。 请确保根据你的库自定义这些值。 仅有的必需参数为
organization、authToken、packageName和version。 其余部分作为扩展示例提供:kotlin// <module directory>/build.gradle.kts npmPublish { organization = "organization_name_without_the_@_sign" registries { npmjs { // 运行发布软件包的命令时, // 你需要将 npm 令牌作为该环境变量传入 authToken = System.getenv("NPM_TOKEN") } } packages { named("js") { version = "0.0.1" packageName = "greetings" readme = file("../README.md") packageJson { license = "Apache 2.0" homepage = "https://github.com/Kotlin/kotlin-multiplatform-web-library#readme" description = "Shared Kotlin/JS Greetings library" keywords = listOf("kotlin", "kotlin-js", "greetings", "shared", "api") author { name = "Kotlin Developer Advocate" url = "https://github.com/kotlin-hands-on/" } contributors = listOf( Person { name = "John Smith" email = "john.smith@example.com" url = "https://github.com/johnsmith" }, ) repository { type = "git" url = "https://github.com/Kotlin/kotlin-multiplatform-web-library.git" } } } } }要配置此项,你也可以使用 Gradle 属性。
npmPublish {} 块中的重要设置包括:
organization参数和registries {}块指定了身份验证详细信息。 在本例中,我们使用主 npm 注册表,以及在运行发布任务时应持有令牌的NPM_TOKEN变量名称。packageName和version参数定义了强制性软件包选项:- 可以省略
version参数,以使用模块的版本作为默认值。 - 可以省略
packageName参数,以使用模块的名称作为默认值。
- 可以省略
packageJson {}块包含各种元数据。
手动发布
在仍在尝试项目结构,或希望自行实现发布自动化时,手动发布会非常有用。
现在你可以从本地计算机将库发布到 npm。 为此,请运行以下命令,将之前生成的访问令牌粘贴到 YOUR_ACCESS_TOKEN 的位置:
NPM_TOKEN=YOUR_ACCESS_TOKEN ./gradlew :shared:publishJsPackageToNpmjsRegistry库发布后,你应该可以在 npm 注册表中看到它。 打开你的 npm 组织页面并检查 Packages 标签页 (而不是你个人的 Packages 页面)。

故障排除
手动发布常出现的一些问题:
- 注意
build.gradle.kts配置中的version字段: 如果软件包已经以相同或更早的版本发布过,npm 将会导致发布失败。 - 为组织作用域软件包生成令牌时, 请确保同时设置常规权限和组织权限。
使用持续集成 (CI) 发布
npm 的 Trusted Publishers 机制允许你使用 OpenID Connect 快速设置 CI。 这种方法完全避免了生成和维护令牌。
在此示例中,我们将使用 GitHub Actions 设置一个工作流。
创建 GitHub Actions 工作流文件
创建一个 .github/workflows/publish.yml 文件来配置 GitHub Action:
# .github/workflows/publish.yml
name: Publish
on:
release:
types: [released, prereleased]
permissions:
id-token: write # GitHub Actions 与 npm 受信任发布集成所必需
contents: read
jobs:
publish:
name: Release build and publish
runs-on: ubuntu-latest
steps:
# 检出触发分支
- name: Check out code
uses: actions/checkout@v4
# 设置用于运行 Gradle 任务的 JDK
- name: Set up JDK 21
uses: actions/setup-java@v4
with:
distribution: 'zulu'
java-version: 21
# 为库模块运行发布的 Gradle 任务
- name: Publish to npm
run: ./gradlew :shared:publishJsPackageToNpmjsRegistry将此文件提交并推送到托管项目的 GitHub 仓库后, 每当你在该仓库中创建 GitHub Release 时,该工作流就会运行。
你还可以将工作流配置为在向仓库推送标记 (tag) 时触发。
将 GitHub Actions 设置为你的 Trusted Publisher
现在你已发布了工作流,可以使用 GitHub Action 为 npm 软件包添加 Trusted Publisher:
- 打开已发布的软件包页面。
- 打开 Settings 标签页并找到 Trusted Publisher 部分。
- 在 Select your publisher 下,点击 GitHub Actions 按钮。
- 填写表单:
- 你的 GitHub 用户名(或组织名)
- 仓库名称
- 工作流文件的名称(在本教程中,我们使用了 publish.yml)。
- 点击 Setup connection 按钮。

npm 不会验证所提供的坐标信息, 因此请确保准确输入详细信息。
创建的连接随后会列在软件包设置的 Trusted Publishers 部分中, 这意味着具有指定坐标的工作流现已获得发布到 npm 的授权。
在 GitHub 上创建 Release
完成工作流和 Trusted Publisher 连接的设置后,你现在可以通过创建 GitHub Release 来触发发布:
在
build.gradle.kts配置中将软件包版本设置为要发布的版本。如果版本号已被使用或低于已发布的版本,npm 将不允许发布。
转到你的 GitHub 仓库。
在右侧边栏中,点击 Releases。
点击 Draft a new release 按钮(如果你之前未曾为此仓库创建过 Release,则点击 Create a new release 按钮)。
创建或选择一个 Git 标记(如果可能,尽量与模块的版本保持一致,以便在各系统之间保持编号一致)。
设置 Release 标题(将 Release 命名为与标记相同的名称会很方便)。
为了方便追踪所有内容,你可能希望标记中的版本与在
build.gradle.kts文件中指定的库版本号相同。
点击 Publish release 按钮。
要检查 Action 是否已触发,请点击 GitHub 仓库页面顶部的 Actions 标签页。 你应该会看到新发布的 Release 触发了发布工作流的运行。 点击该工作流即可查看发布任务的日志。
工作流运行完成后,新版本的软件包应列在 npm 注册表中的软件包页面上。

