Skip to content

將你的程式庫發佈至 npm – 教學 ​

手動或使用 GitHub Actions,透過 npm-publish Gradle 外掛程式將你的 Kotlin Multiplatform 程式庫發佈至 npm。

若要發佈你的程式庫,你將需要:

  1. 準備憑據,包括 npm 帳戶 以及 存取權杖。
  2. 在你的 Kotlin Multiplatform 專案中配置發佈外掛程式。
  3. 為發佈外掛程式提供憑據,或為持續整合設定 Trusted Publisher。
  4. 手動或使用 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 專案:

  1. 開啟你的程式庫模組的 build.gradle.kts 檔案。

  2. 在 plugins {} 區塊中新增以下內容:

    kotlin
    // <module directory>/build.gradle.kts
    
    plugins {
        kotlin("npm-publish") version "3.7.0"
    }

    若要查看外掛程式的最新可用版本,請查看 Releases 頁面。

  3. 新增以下配置。 請務必根據你的程式庫自訂這些值。 唯一必要的參數為 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 registry,以及在執行發佈任務時應存放權杖的 NPM_TOKEN 變數名稱。
  • packageName 與 version 參數定義了必要的軟件包選項:
    • 可以省略 version 參數,以使用你模組的版本作為預設值。
    • 可以省略 packageName 參數,以使用你模組的名稱作為預設值。
  • packageJson {} 區塊包含各種元資料。

手動發佈 ​

當你仍在嘗試專案結構,或希望自行實作發佈自動化時,手動發佈會非常有用。

現在你可以從本機電腦將程式庫發佈至 npm。 若要執行此操作,請執行以下指令,並將先前產生的存取權杖貼在 YOUR_ACCESS_TOKEN 位置:

bash
NPM_TOKEN=YOUR_ACCESS_TOKEN ./gradlew :shared:publishJsPackageToNpmjsRegistry

程式庫發佈完成後,你應該能夠在 npm registry 中看到它。 開啟你的 npm 組織頁面並檢查 Packages 分頁 (而非個人 Packages 頁面)。

在 npm 上發佈的程式庫

疑難排解 ​

手動發佈時常出現的幾個問題:

  • 隨時注意 build.gradle.kts 配置中的 version 欄位: 如果軟件包已使用相同或更早的版本發佈過,npm 的發佈將會失敗。
  • 為作用域套件(organization-scoped package)產生權杖時,請確保同時設定了一般與組織權限。

使用持續整合 (CI) 發佈 ​

npm 的 Trusted Publishers 機制可讓你使用 OpenID Connect 快速設定 CI。 這種方法完全避免了產生與維護權杖的麻煩。

在本範例中,我們將使用 GitHub Actions 設定一個工作流程。

建立 GitHub Actions 工作流程檔案 ​

建立一個配置 GitHub action 的 .github/workflows/publish.yml 檔案:

yaml
# .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

      # 設定 JDK 以執行 Gradle 任務
      - 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 時,此工作流程就會執行。

你也可以將工作流程配置為在推送標籤時觸發。

將 GitHub Actions 設定為你的 Trusted Publisher ​

現在你已經發佈了工作流程,可以使用 GitHub Action 為你的 npm 軟件包新增 Trusted Publisher:

  1. 開啟已發佈的軟件包頁面。
  2. 開啟 Settings 分頁並找到 Trusted Publisher 區段。
  3. 在 Select your publisher 下方,點擊 GitHub Actions 按鈕。
  4. 填寫表單:
    • 你的 GitHub 名稱(或組織)
    • 存儲庫名稱
    • 工作流程檔案名稱(在本教學中,我們使用了 publish.yml)。
  5. 點擊 Setup connection 按鈕。

針對 GitHub Actions 的 npm Trusted Publisher 設定

npm 不會驗證提供的座標資訊,因此請確保輸入的詳細資料正確無誤。

建立好的連線隨後會列在軟件包設定的 Trusted Publishers 區段中,這表示具有指定座標資訊的工作流程現在已獲得授權可發佈至 npm。

在 GitHub 上建立 Release ​

設定好工作流程與 Trusted Publisher 連線後,你現在可以透過建立 GitHub release 來觸發發佈:

  1. 將 build.gradle.kts 配置中的軟件包版本設定為你想要發佈的版本。

    如果版本號已被使用或低於已發佈的版本,npm 將不允許發佈。

  2. 前往你的 GitHub 存儲庫。

  3. 在右側邊欄中,點擊 Releases。

  4. 點擊 Draft a new release 按鈕(如果之前未曾為此存儲庫建立過 release,則點擊 Create a new release 按鈕)。

  5. 建立或選取一個 Git 標籤(如果可能,請與模組版本相符,以保持不同系統間編號的一致性)。

  6. 設定 release 標題(將 release 命名為與標籤相同的名稱會很方便)。

    為了掌握所有內容,你可能會希望標籤中的版本與你在 build.gradle.kts 檔案中指定的程式庫版本號相同。

    在 GitHub 上建立 release

  7. 點擊 Publish release 按鈕。

若要檢查 Action 是否已被觸發,請點擊 GitHub 存儲庫頁面頂端的 Actions 分頁。 你應該會看到新發佈的 release 觸發了發佈工作流程的執行。 點擊該工作流程以查看發佈任務的日誌。

工作流程執行完成後,新版本的軟件包應會列在 npm registry 中的軟件包頁面上。

透過 CI/CD 在 npm 上發佈的程式庫

後續步驟 ​