跳到主要內容
JSR 首頁|登入

檢視目錄表

與 npm 相容

透過 JSR 的 npm 相容性層，使用 npm 和 node_modules 的工具可以使用 JSR。例如：Node.js、Cloudflare Workers、Vite、Esbuild、Webpack 和 Rollup。

如果您使用的是 Deno，則您可以使用 jsr: 輸入。

有了這個相容性層，所有的 JSR 套件都可以使用現有的與 npm 相容的套件管理員（例如 npm、yarn 和 pnpm）進行安裝。這表示您可以使用 node_modules 在任何支援 npm 套件的工具中使用 JSR 套件。使用這個相容性層時，您可以像往常一樣使用 npm install / yarn add / pnpm install 安裝 JSR 套件。JSR 套件會從 jsr.io 下載並安裝到您的 node_modules 目錄中。

安裝與使用 JSR 套件

你可以透過命令列界面工具 jsr 將 JSR 套件加入到你的專案當中

npx jsr add @luca/cases

這將會將 @luca/cases 套件加入你的 package.json 檔案中，並使用你偏好的套件管理員將此套件安裝到你的 node_modules 目錄底下。

預設情況下，將會根據你的專案中是否存在 package.lock、yarn.lock 或 pnpm-lock.yaml 檔案，自動偵測要使用的套件管理員。你也可以在 jsr add 指令中使用 --npm、--yarn 或 --pnpm 標記，明確指定要使用的套件管理員。

你應當檢查已建立至原始程式碼控制檔案中的 .npmrc 檔案。這能讓後續 npm install / yarn / pnpm install 命令呼叫成功執行。

接著你就可以在你自己的程式碼中使用 JSR 套件

import { camelCase } from "@luca/cases";

注意：由於 npm 和 yarn 的限制，有時它們可能會安裝重複的 JSR 相依套件。這會導致 node_modules 目錄比必要時還要來得大，而且對某些套件而言，這可能會導致發生預期之外的行為。我們建議你使用 pnpm 來獲得最佳使用體驗。

限制

JSR npm 相容性層並非原生 JSR 支援的完美替代品。有一些限制

  • 你無法使用 jsr: 規範子來匯入 JSR 套件。
  • 與原生 JSR 匯入不同，你不會直接匯入 TypeScript 程式碼。相反地，JSR 會在轉譯 TypeScript 程式碼成 JavaScript 之後，才會將其安裝到你的 node_modules 目錄裡頭。這通常表示你的編輯器使用體驗很可能會變差，因為「移至定義」與其他功能將會連結到已轉譯的 JavaScript 程式碼，或是連結到已產生的 .d.ts 檔案。
  • 通常來說，安裝時間會比使用原生 JSR 支援時還慢，因為 npm 將會下載檔案，即使專案中並未使用這些檔案。
  • 你無法使用 npm publish，透過 npm 相容性層公開 JSR 套件。你只能使用 jsr publish 或 deno publish 來公開 JSR 套件。

進階設定

JSR npm 相容性層的工作原理是讓所有 JSR 套件都在特殊的 @jsr npm 範圍下可用。@jsr npm 範圍不是一個實際的 npm 範圍，你無法將套件發布到此範圍。你只能使用它從 npm 安裝 jsr 套件。

@jsr npm 範圍從 https://npm.jsr.io 的 JSR 註冊服務中載入。這表示你需要設定你的套件管理員使用此註冊服務來安裝 JSR 套件。如果使用 jsr CLI 來新增套件，此動作會自動執行。

你可以不使用 jsr CLI 安裝 JSR 套件，也可以手動設定你的套件管理員來支援安裝 JSR 套件。

為此，請建立 .npmrc 檔案，並將以下行加入其中

@jsr:registry=https://npm.jsr.io

這會指示你的套件管理員從 JSR 後端載入 @jsr 範圍中的所有套件，而不是從 npm 載入。

你也可以透過在你的主目錄中建立一個內容相同的 .npmrc 檔案，來設定你的套件管理員在你的機器上的所有專案都支援 JSR。

接著你可以手動使用 npm install / yarn add / pnpm install，並使用特殊的 @jsr npm 範圍來安裝 JSR 套件

npm install @jsr/luca__cases@1 # installs the @luca/cases package from JSR
yarn add @jsr/luca__cases@1 # installs the @luca/cases package from JSR
pnpm install @jsr/luca__cases@1 # installs the @luca/cases package from JSR

@jsr/ 範圍後的名稱是你想要安裝的 JSR 套件的名稱。此名稱與你會在 jsr: 輸入中使用的套件名稱相同，但已移除範圍前綴 @，並且範圍和名稱之間的 / 已取代為 __。

例如，jsr:@luca/cases 套件可以在 @jsr/luca__cases 中取得。

接著，你可以在你的程式碼中使用 @jsr 範圍來輸入 JSR 套件

import { camelCase } from "@jsr/luca__cases";

如果你想要輸入套件但不需要指定 @jsr/，你可以更新 package.json 中的 dependencies 物件

 // package.json
 {
   "type": "module",
   "dependencies": {
-    "@jsr/luca__cases": "1"
+    "@luca/cases": "npm:@jsr/luca__cases@1"
   }
 }

接著，你可以在使用 package.json 中定義的名稱來輸入套件

import { camelCase } from "@luca/cases";

技術詳細資料

@jsr npm 範圍是一種特殊範圍，用於將 JSR 套件對應到在原生不支援 JSR 的系統中的 npm 套件。@jsr npm 範圍並非真正的 npm 範圍，且您無法發佈套件至該範圍。您只能使用它來從 npm 安裝 JSR 套件。

@jsr 套件並不是由位於 https://registry.npmjs.org 的 npm 登錄來提供的。相反地，它們是由位於 https://npm.jsr.io 的 JSR 登錄來提供的。此終端點會施行 npm 登錄 API。例如，要取得 @jsr/luca__cases 套件的資料，您可以將 GET 要求傳送至 https://npm.jsr.io/@jsr/luca__cases。

此終端點會提供 npm 相容的 tarball 給 @jsr 套件。這些 tarball 由 JSR 產生，且包含所有可以從套件進入點存取的原始程式碼。此原始程式碼會轉譯成 JavaScript，且會針對所有 TypeScript 檔案產生 TypeScript 類型的宣告（.d.ts 檔案）。此 tarball 也包含 package.json 檔案，其中包含自原始 jsr.json/deno.json 檔案的 exports 欄位。

已刪除版本的套件不會在 npm 登錄終端點的套件版本資訊檔中宣傳。即使在版本被刪除後，被刪除版本的 tarball 仍然可以使用，這代表有在鎖定檔案中參考被刪除版本的工具仍然可以安裝該版本。

針對特定套件版本宣傳的特定 tarball 可能會隨時間而改變，即使該版本本身未變更。這是因為 JSR 登錄可能會針對套件版本重新產生 npm 相容的 tarball 來修正與 npm 的相容性問題或改善產生 tarball 中的轉譯輸出。我們將此稱為 tarball 的「修訂」。tarball 的修訂並未在 npm 登錄終端點中宣傳，但它包含在 tarball 本身的 URL 中，且包含在 tarball 中 package.json 檔案的 _jsr_revision 欄位中。tarball 的修訂不被視為套件版本的一部分，且不會影響 semver 解析。

然而，tarball URL 是不可變的。有參考特定 tarball URL 的工具將始終能夠下載該確切的 tarball。當產生 tarball 的新修訂時，舊的 tarball 不會被刪除，且會持續在相同的 URL 中提供。新的 tarball 會在包含新修訂的新 URL 中提供。

由於 tarball URL 會包含在套件管理員鎖定檔案中，執行 npm i/yarn/pnpm i 將永遠不會意外下載新的 tarball 修訂。

在 GitHub 上編輯此頁面