前往主要內容
JSR Home|登入

查看目錄清單

發布套件

您可以將大多數使用 ESM 模組撰寫的 JavaScript 和 TypeScript 程式碼發布為 JSR 套件。JSR 套件會發布至 jsr.io，且可從Deno、Node.js 和其他工具匯入。 瞭解更多有關使用套件的資訊。

最初撰寫而使用 package.json 的程式碼，以及最初為 Deno 編寫的程式碼，皆可發布為 JSR 套件。JSR 支援並鼓勵發布 TypeScript 原始碼，而非成對的 .js + .d.ts 檔案。這讓 JSR 能提供更實用的自動產生文件，並有助於在編輯器中提供更完善的自動完成功能。

JSR 套件規則

上傳到 JSR 的所有套件在發佈時，會自動處理並驗證，以確保所有在 JSR 上主機的程式碼都符合一致性的規則集。這些規則旨在讓您可以在各種不同的環境中移植程式碼。您的程式碼必須遵循這些規則，才能在 JSR 上發佈。

  • 僅限 ESM 模組：JSR 套件以 ESM 模組發佈。這表示您只能發佈使用 import 和 export 關鍵字的模組。您不能發佈 CommonJS 模組。
  • 支援 npm 套件：您可以透過在 package.json 的 dependencies 中指定，或在程式碼中使用 npm: 說明符參照 (例如 import { cloneDeep } from "npm:lodash@4";) 的方式，來依賴 npm 套件。
  • 支援 jsr 套件：您可以透過在 package.json 的 dependencies 中指定，或在程式碼中使用 jsr: 說明符參照 (例如 import { encodeBase64 } from "jsr:@std/encoding@1/base64";) 的方式，來依賴 JSR 套件。
  • 支援 node: 內建函式：您可以使用 node: 架構匯入 Node.js 內建函式。例如，您可以使用 import { readFile } from "node:fs"; 匯入 fs 模組。假如您的套件有 package.json，您也可以使用空說明符 (不加上 node: 前綴) 來匯入 Node.js 內建函式。
  • 使用簡潔的檔名：檔名必須與 Windows 和 Unix 相容。這表示檔名不能包含像 *、: 或 ? 等字元。您也不能有多個檔名相同，但大小寫不同的檔案。
  • 建議避免使用 TypeScript「緩慢型別」：為加速型別檢查、支援文件產生和 Node.js 相容性，JSR 套件不應在匯出的函式、類別或變數中使用某些 TypeScript 型別。這項原則預設實施，但您可以選擇不實施。進一步了解「緩慢型別」。
  • 有效的文件間匯入：您套件中所有模組之間的相對匯入都必須在發佈時就能解析。支援的說明符格式取決於有無使用 package.json，詳細說明如下。

撰寫程式碼

僅限 ESM

要發佈 JSR 套件，你必須先撰寫套件的程式碼。JSR 套件使用 JavaScript 或 TypeScript 撰寫，並作為 ESM 模組發佈。

// greet.ts
/**
 * Greet a person.
 * @param name The name of the person to greet.
 */
export function greet(name: string) {
  console.log(`Hello, ${name}!`);
}

相對引入

一個套件可以由多個模組組成。你可以使用相對路徑引入套件中的其他模組。你應該在引入時使用正確的副檔名，例如引入 greet.ts 時，使用 ./greet.ts 而不是 ./greet 或 ./greet.js。

你的套件中有 package.json 時，模組可以使用「隨便引入」。有了「隨便引入」功能，你可以在引入檔案時省略副檔名，或是使用 .js 副檔名，即使實際上的檔案是 .ts。你也可以透過 index.js 解析，使用目錄引入。

// mod.ts
/**
 * A module providing a function to greet people.
 *
 * @example
 * ```ts
 * import { greet } from "@luca/greet";
 *
 * greet("Luca");
 * ```
 *
 * @module
 */

export * from "./greet.ts";

引入 npm 套件

你可以引入在 "dependencies" 中規定的 package.json npm 套件，或是 deno.json、載入地圖中規定的 npm 套件，或是在原始程式碼中使用 npm: 說明符規定的 npm 套件。

// package.json
{
  "dependencies": {
    "chalk": "5"
  }
}
// mod.ts
import * as chalk from "chalk";

import * as express from "npm:express@4";

深入了解如何透過套件進行使用。

// package.json
{
  "dependencies": {
    "@std/encoding": "npm:@jsr/std__encoding@1"
  }
}
// mod.ts
import * as encoding from "@std/encoding";

import { camelCase } from "jsr:@luca/cases@1";

匯入 Node.js 內建函式

使用 node: 架構，即可匯入 Node.js 內建函式。如果套件中存在 package.json，您也可以省略 node: 架構。

// mod.ts
import { readFileSync } from "node:fs";

export function readJsonFile(path: string) {
  return JSON.parse(readFileSync(path, "utf8"));
}

相依性清單

您可以使用相依性清單（例如 package.json）或 匯入地圖（例如 deno.json 檔案）來簡化匯入。發布期間，jsr publish / deno publish 會自動將原始程式碼中的規格符號改寫為完全限定規格符號，這些規格符號不再需要匯入地圖 / package.json。

// import_map.json / deno.json
{
  "imports": {
    "@luca/greet": "jsr:@luca/greet@1",
    "@std/path": "jsr:@std/path@1"
  }
}
// mod.ts
export { greet } from "@luca/greet";
export { join } from "@std/path";

避免使用執行速度較慢的類型

撰寫 TypeScript 時，請務必確保您的程式碼不使用「執行速度較慢的類型」，否則 JSR 將無法建立文件、為 npm 相容層產生類型宣告，以及加快套件消費者的類型檢查速度。深入了解「執行速度較慢的類型」。

你可以使用 --allow-slow-types 旗標暫時繞過此限制。這將導致你的所有使用者在類型檢查時的速度顯著下降。此外，文件產出和節點相容性還會受到影響。考慮修正速度較慢的類型以避免這些缺點，而不是使用此旗標。

封包組態檔

寫好程式碼之後，你必須將一份組態檔新增到封包中。此檔包含封包的元資料，例如名稱、版本和進入點。這份檔案應該命名為 jsr.json。Deno 使用者也可以將所需的 JSR 屬性加到他們的 deno.json 中，以避免建立另一個檔案。

// jsr.json / deno.json
{
  "name": "@luca/greet",
  "version": "1.0.0",
  "exports": "./mod.ts"
}

深入瞭解如何 組態 JSR 封包。

建立範圍和封包

JSR 被組織為範圍。範圍是封包的集合。範圍類似於 npm 組織。範圍會加上一個 @ 符號為前綴，後面接上一個名稱。例如，@luca 就是一個範圍。

你可以前往 jsr.io/new 來建立一個範圍。範圍名稱必須長度在 2 到 32 個字元之間，只能包含小寫字母、數字和連字號。你只能在尚未被使用的名稱下建立範圍。非常類似於現有範圍名稱的範圍名稱（例如，只差一個連字號）是被禁止的。深入瞭解範圍。

在你建立一個範圍後，你可以在該範圍中建立一個封包。你可以前往 jsr.io/new 來建立一個封包。封包名稱必須長度在 2 到 20 個字元之間，只能包含小寫字母、數字和連字號。你只能在尚未被使用的名稱下建立封包。非常類似於現有封包名稱的封包名稱（例如，只差一個連字號）是被禁止的。深入瞭解封包。

驗證套件

要發布套件（包含執行預先執行來確認套件符合所有 JSR 規則），需要使用 jsr publish 或 deno publish。兩種指令的語法大致相同。您可以依據工具用以下方式呼叫發布指令。

# deno
deno publish
# npm
npx jsr publish
# yarn
yarn dlx jsr publish
# pnpm
pnpm dlx jsr publish

您可以使用 --dry-run 標記執行 jsr publish 來進行在實際發布時會發生的所有發布驗證。這將列印出會發布的檔案清單，但會在實際發布至登錄時停止。

# deno
$ deno publish --dry-run
# npm
$ npx jsr publish --dry-run
# yarn
yarn dlx jsr publish --dry-run
# pnpm
pnpm dlx jsr publish --dry-run

從本機發布

您可以使用 jsr publish 或 deno publish 指令從本機發布套件。

將透過您的瀏覽器進行驗證，因此您不需要向 CLI 提供任何憑證。

輸入套件的根目錄（包含 jsr.json / deno.json 檔案），然後執行 jsr publish。

# deno
$ deno publish
# npm
$ npx jsr publish
# yarn
yarn dlx jsr publish
# pnpm
pnpm dlx jsr publish

當您執行 jsr publish 時，CLI 將開啟您的瀏覽器以核准發布。如果您尚未登入，系統將提示您使用 JSR 帳戶登入。登入後，系統將提示您授權 CLI 存取您嘗試發布的特定套件。按一下「允許」來授權 CLI 存取。

CLI 現在會將您的套件上傳到 JSR 登錄。上傳完成後，CLI 將輸出您可以在 JSR 網站上檢視套件的網址。

在發布期間，JSR CLI 和 JSR 伺服器都將針對您的套件執行許多檢查，以確保其有效。如果其中任何檢查失敗，CLI 將輸出錯誤訊息。您必須修正這些錯誤才能再次嘗試發布。 進一步了解如何解決發布錯誤。

從 GitHub Actions 發布

JSR 提供一流支援，可從 GitHub Actions 發布套件。這允許你自動從 CI 發布套件，無需設定任何機密或驗證。

要從 GitHub Actions 發布，你必須先在 JSR 中從你的套件設定連結你的套件到你的 GitHub 儲存庫。為此，請前往你在 jsr.io 上的套件的設定標籤，輸入你的 GitHub 儲存庫名稱，然後按一下「連結」。

將你的套件連結到你的 GitHub 儲存庫後，你可以從 GitHub Actions 發布。為此，在你的儲存庫中建立一個工作流程檔案，例如 .github/workflows/publish.yml。在此工作流程檔案中，你可以建立一個使用 jsr publish 指令來發布套件的工作。

# .github/workflows/publish.yml

name: Publish

on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write # The OIDC ID token is used for authentication with JSR.    
    steps:
      - uses: actions/checkout@v4
      - run: npx jsr publish

每當你在推送到儲存庫的 main 分支時，此工作流程就會執行。它會將你的套件發布到 JSR，並且會根據你的 jsr.json 檔案中的版本自動使用正確的版本編號。如果 jsr.json 檔案中指定的版本已經發布到 JSR，則 jsr publish 就不會嘗試發布。

篩選檔案

jsr publish 會略過套件根目錄下 .gitignore 檔案中列出的檔案。此外，你可以在 jsr.json/deno.json 檔案中指定 include 和 exclude 欄位，以包含、略過或取消對特定檔案不套用 gitignore。

例如，若要只選擇性包含某些檔案，你可以使用 include 選項指定符合所有檔案的 glob

// jsr.json
{
  "name": "@luca/greet",
  "version": "1.0.0",
  "exports": "./src/mod.ts",
  // note: this will be collapsed down to just include in the future
  "publish": {
    "include": [
      "LICENSE",
      "README.md",
      "src/**/*.ts"
    ]
  }
}

你也可以透過 exclude 選項排除某些檔案

// jsr.json
{
  "name": "@luca/greet",
  "version": "1.0.0",
  "exports": "./src/mod.ts",
  "publish": {
    "include": [
      "LICENSE",
      "README.md",
      "src/**/*.ts"
    ],
    "exclude": [
      "src/tests"
    ]
  }
}

在使用 Deno 時，deno.json 中的 include 和 exclude 選項也會用於許多其他 Deno 子指令，例如 deno test 和 deno bundle。你可以在 deno.json 檔案中使用 publish.include 和 publish.exclude 來指定只套用到 deno publish 的選項。

// deno.json
{
  "name": "@luca/greet",
  "version": "1.0.0",
  "exports": "./dist/mod.ts",
  "publish": {
    "include": ["src"],
    "exclude": ["src/tests"]
  }
}

取消忽略未使用「include」時的檔案

您的套件可能有包含以下內容的 .gitignore 檔案

.env
dist/

在此情況下，dist/ 目錄中的任何檔案，以及命名為 .env 的任何檔案在發布時將會被忽略。

但是，如果您想發布 dist/ 目錄，這可能會不方便，因為您有指向它的（或它的子目錄）“exports”。在此情況下，您可以透過在 jsr.json / deno.json 檔案的 exclude 欄位中使用否定來取消忽略 dist/ 目錄。

// jsr.json
{
  "name": "@luca/greet",
  "version": "1.0.0",
  "exports": "./dist/mod.ts",
  "publish": {
    "exclude": ["!dist"]
  }
}

在此情況下，即使 dist/ 目錄列於 .gitignore 檔案中，它仍會在發布時納入。

在 GitHub 上編輯此頁面