跳至主要內容
版本：9.x

package.json

套件的清單檔案。包含所有套件的元資料，包括依賴項、標題、作者等。這是所有主要 Node.JS 套件管理員（包括 pnpm）保留的標準。

engines​

您可以指定軟體運作的 Node 和 pnpm 版本

{
    "engines": {
        "node": ">=10",
        "pnpm": ">=3"
    }
}

在進行本機開發期間，如果 pnpm 版本與 engines 欄位指定的版本不符，pnpm 將會持續傳回錯誤訊息。

除非使用者已設定 engine-strict 設定旗標（請參閱 .npmrc），否則此欄位僅供參考，且僅會在套件安裝為依賴項時產生警告。

dependenciesMeta​

用於 dependencies、optionalDependencies 和 devDependencies 內部所宣告依賴項的額外元資料。

dependenciesMeta.*.injected​

如果這項設定為 true，則本機依賴項會硬連結至虛擬儲存體 (node_modules/.pnpm)，並從虛擬儲存體符號連結至模組目錄。

如果將此設定為 false 或未設定為本機相依性，套件將會直接從工作區中的位置符號連結到模組目錄。

例如，工作區中的下列 package.json 會在 card 的 node_modules 目錄中建立一個符號連結至 button

{
  "name": "card",
  "dependencies": {
    "button": "workspace:1.0.0"
  }
}

但是，如果 button 在其同儕相依性中包含 react 呢？如果單一儲存庫中的所有專案都使用相同版本的 react，則沒有問題。但是，如果 button 是由使用 react@16 的 card 和使用 react@17 的 form 所需要呢？如果不使用 inject，您必須選擇單一版本的 react 並將其安裝為 button 的開發相依性。但是，使用 injected 欄位，您可以將 button 注入到套件中，而 button 將會使用該套件的 react 版本安裝。

因此，這將會是 card 的 package.json

{
  "name": "card",
  "dependencies": {
    "button": "workspace:1.0.0",
    "react": "16"
  },
  "dependenciesMeta": {
    "button": {
      "injected": true
    }
  }
}

button 將會硬連結到 card 的相依性，而 react@16 將會符號連結到 card/node_modules/button 的相依性。

而這將會是 form 的 package.json

{
  "name": "form",
  "dependencies": {
    "button": "workspace:1.0.0",
    "react": "17"
  },
  "dependenciesMeta": {
    "button": {
      "injected": true
    }
  }
}

button 將會硬連結到 form 的相依性，而 react@17 將會符號連結到 form/node_modules/button 的相依性。

與一般相依性相反，注入的相依性不會符號連結到目的地資料夾，因此它們不會自動更新，例如在執行建置指令碼後。若要將硬連結的資料夾內容更新為相依性套件資料夾的最新狀態，請再次呼叫 pnpm i。

請注意，button 套件必須具有任何在安裝時執行的生命週期指令碼，才能讓 pnpm 偵測變更並更新它。例如，套件可以在安裝時重新建置："prepare": "pnpm run build"。任何指令碼都可以使用，甚至是一個沒有副作用的簡單無關指令，例如："prepare": "pnpm root"。

peerDependenciesMeta​

此欄位會列出與 peerDependencies 欄位中所列相依性相關的一些額外資訊。

peerDependenciesMeta.*.optional​

如果將此設定為 true，套件管理員將會將所選的同儕相依性標記為選用。因此，使用者省略它將不再被報告為錯誤。

例如

{
    "peerDependencies": {
        "foo": "1"
    },
    "peerDependenciesMeta": {
        "foo": {
            "optional": true
        },
        "bar": {
            "optional": true
        }
    }
}

請注意，即使 bar 未在 peerDependencies 中指定，它仍會被標記為選用。因此，pnpm 將假設任何版本的 bar 都可以。然而，foo 是選用的，但僅限於必要的版本規格。

publishConfig​

可以在套件封裝之前覆寫清單中的某些欄位。可以覆寫下列欄位

若要覆寫欄位，請將欄位的發布版本新增至 publishConfig。

例如，下列 package.json

{
    "name": "foo",
    "version": "1.0.0",
    "main": "src/index.ts",
    "publishConfig": {
        "main": "lib/index.js",
        "typings": "lib/index.d.ts"
    }
}

會發布為

{
    "name": "foo",
    "version": "1.0.0",
    "main": "lib/index.js",
    "typings": "lib/index.d.ts"
}

publishConfig.executableFiles​

預設情況下，基於可攜性的原因，在產生的封存套件中，只有 bin 欄位中列出的檔案會標記為可執行。executableFiles 欄位可讓您宣告必須設定可執行標記 (+x) 的其他欄位，即使無法透過 bin 欄位直接存取這些欄位。

{
  "publishConfig": {
    "executableFiles": [
      "./dist/shim.js"
    ]
  }
}

publishConfig.directory​

您也可以使用 publishConfig.directory 欄位，自訂相對於目前 package.json 的發布子目錄。

預期在指定的目錄中會有目前套件的修改版本（通常使用第三方建置工具）。

在此範例中，"dist" 資料夾必須包含 package.json

{
  "name": "foo",
  "version": "1.0.0",
  "publishConfig": {
    "directory": "dist"
  }
}

publishConfig.linkDirectory​

  • 預設值：true
  • 類型：布林值

設定為 true 時，專案會在本地端開發期間從 publishConfig.directory 位置建立符號連結。

例如

{
  "name": "foo",
  "version": "1.0.0",
  "publishConfig": {
    "directory": "dist"
    "linkDirectory": true
  }
}

pnpm.overrides​

此欄位可讓您指示 pnpm 覆寫依存關係圖中的任何依存關係。這有助於強制所有套件使用依存關係的單一版本、回溯修正，或以分支取代依存關係。

請注意，overrides 欄位只能設定在專案的根目錄。

"pnpm"."overrides" 欄位的範例

{
  "pnpm": {
    "overrides": {
      "foo": "^1.0.0",
      "quux": "npm:@myorg/quux@^1.0.0",
      "bar@^2.1.0": "3.0.0",
      "qar@1>zoo": "2"
    }
  }
}

您可以透過使用「>」將套件選擇器與依存關係選擇器分開，指定覆寫的依存關係所屬的套件，例如 qar@1>zoo 將只會覆寫 qar@1 的 zoo 依存關係，不會覆寫任何其他依存關係。

覆寫可以定義為對直接依存關係規格的參照。這可透過在依存關係名稱前加上 $ 來達成

{
  "dependencies": {
    "foo": "^1.0.0"
  },
  "pnpm": {
    "overrides": {
      "foo": "$foo"
    }
  }
}

參照的套件不需要與覆寫的套件相符

{
  "dependencies": {
    "foo": "^1.0.0"
  },
  "pnpm": {
    "overrides": {
      "bar": "$foo"
    }
  }
}

pnpm.packageExtensions​

packageExtensions 欄位提供一種方式，可使用其他資訊來擴充現有的套件定義。例如，如果 react-redux 應該在 peerDependencies 中包含 react-dom，但它沒有，則可以使用 packageExtensions 來修補 react-redux

{
  "pnpm": {
    "packageExtensions": {
      "react-redux": {
        "peerDependencies": {
          "react-dom": "*"
        }
      }
    }
  }
}

packageExtensions 中的鍵是套件名稱或套件名稱和 semver 範圍，因此可以修補套件的某些版本

{
  "pnpm": {
    "packageExtensions": {
      "react-redux@1": {
        "peerDependencies": {
          "react-dom": "*"
        }
      }
    }
  }
}

下列欄位可以使用 packageExtensions 進行擴充：dependencies、optionalDependencies、peerDependencies 和 peerDependenciesMeta。

較大的範例

{
  "pnpm": {
    "packageExtensions": {
      "express@1": {
        "optionalDependencies": {
          "typescript": "2"
        }
      },
      "fork-ts-checker-webpack-plugin": {
        "dependencies": {
          "@babel/core": "1"
        },
        "peerDependencies": {
          "eslint": ">= 6"
        },
        "peerDependenciesMeta": {
          "eslint": {
            "optional": true
          }
        }
      }
    }
  }
}
提示

我們與 Yarn 共同維護一個 packageExtensions 資料庫，用於修補生態系統中已損壞的套件。如果您使用 packageExtensions，請考慮發送 PR 上游並將您的擴充貢獻給 @yarnpkg/extensions 資料庫。

pnpm.peerDependencyRules​

pnpm.peerDependencyRules.ignoreMissing​

pnpm 對於此清單中遺失的同儕相依性不會列印警告。

例如，使用下列組態後，如果相依性需要 react 但未安裝 react，pnpm 就不會列印警告

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["react"]
    }
  }
}

也可以使用套件名稱模式

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["@babel/*", "@eslint/*"]
    }
  }
}

pnpm.peerDependencyRules.allowedVersions​

對於指定範圍的同儕相依性，不會列印未滿足的同儕相依性警告。

例如，如果您有一些相依性需要 react@16，但您知道它們與 react@17 搭配使用也能正常運作，那麼您可以使用下列組態

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "react": "17"
      }
    }
  }
}

這會告訴 pnpm 任何在同儕相依性中包含 react 的相依性都應該允許安裝 react v17。

也可以僅針對特定套件的對等相依性抑制警告。例如，在下列設定中，react v17 僅在它是 button v2 套件的對等相依性或任何 card 套件的相依性時才會被允許

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "button@2>react": "17",
        "card>react": "17"
      }
    }
  }
}

pnpm.peerDependencyRules.allowAny​

allowAny 是套件名稱樣式的陣列，任何符合樣式的對等相依性都將從任何版本解析，而不論在 peerDependencies 中指定的範圍。例如

{
  "pnpm": {
    "peerDependencyRules": {
      "allowAny": ["@babel/*", "eslint"]
    }
  }
}

上述設定將靜音任何與 @babel/ 套件或 eslint 相關的對等相依性版本不符的警告。

pnpm.neverBuiltDependencies​

此欄位允許忽略特定相依性的建置。在安裝期間，列出的套件的「preinstall」、「install」和「postinstall」指令碼將不會執行。

"pnpm"."neverBuiltDependencies" 欄位的範例

{
  "pnpm": {
    "neverBuiltDependencies": ["fsevents", "level"]
  }
}

pnpm.onlyBuiltDependencies​

允許在安裝期間執行的套件名稱清單。如果此欄位存在，只有列出的套件才能執行安裝指令碼。

範例

{
  "pnpm": {
    "onlyBuiltDependencies": ["fsevents"]
  }
}

pnpm.onlyBuiltDependenciesFile​

此設定選項允許使用者指定 JSON 檔案，其中列出在 pnpm 安裝過程中唯一允許執行安裝指令碼的套件。透過使用此功能，您可以增強安全性或確保只有特定相依性在安裝期間執行指令碼。

範例

{
  "dependencies": {
    "@my-org/policy": "1.0.0"
  },
  "pnpm": {
    "onlyBuiltDependenciesFile": "node_modules/@my-org/policy/onlyBuiltDependencies.json"
  }
}

JSON 檔案本身應包含套件名稱陣列

node_modules/@my-org/policy/onlyBuiltDependencies.json
[
  "fsevents"
]

pnpm.allowedDeprecatedVersions​

此設定允許靜音特定套件的廢棄警告。

範例

{
  "pnpm": {
    "allowedDeprecatedVersions": {
      "express": "1",
      "request": "*"
    }
  }
}

在上述設定中，pnpm 將不會列印關於任何 request 版本和 express 的 v1 的廢棄警告。

pnpm.patchedDependencies​

當您執行 pnpm patch-commit 時，此欄位會自動新增/更新。它是一個字典，其中金鑰應該是套件名稱和確切版本。值應該是修補程式檔案的相對路徑。

範例

{
  "pnpm": {
    "patchedDependencies": {
      "express@4.18.1": "patches/express@4.18.1.patch"
    }
  }
}

pnpm.allowNonAppliedPatches​

當為 true 時，如果未套用 patchedDependencies 欄位中部分修補程式，安裝作業不會失敗。

{
  "pnpm": {
    "patchedDependencies": {
      "express@4.18.1": "patches/express@4.18.1.patch"
    },
    "allowNonAppliedPatches": true
}

pnpm.updateConfig​

pnpm.updateConfig.ignoreDependencies​

有時您無法更新相依性。例如，相依性的最新版本開始使用 ESM，但您的專案尚未使用 ESM。令人討厭的是，當執行 pnpm update --latest 時，pnpm outdated 指令會一直列印出此類套件並更新。不過，您可以在 ignoreDependencies 欄位中列出不想升級的套件

{
  "pnpm": {
    "updateConfig": {
      "ignoreDependencies": ["load-json-file"]
    }
  }
}

也支援樣式，因此您可以忽略範圍中的任何套件：@babel/*。

pnpm.auditConfig​

pnpm.auditConfig.ignoreCves​

pnpm audit 指令會忽略的 CVE ID 清單。

{
  "pnpm": {
    "auditConfig": {
      "ignoreCves": [
        "CVE-2022-36313"
      ]
    }
  }
}

pnpm.requiredScripts​

列在此陣列中的指令碼會在工作區的每個專案中需要。否則，pnpm -r run <script name> 會失敗。

{
  "pnpm": {
    "requiredScripts": ["build"]
  }
}

pnpm.supportedArchitectures​

您可以指定要為其安裝選用相依性的架構，即使它們與執行安裝的系統架構不符。

例如，下列設定會指示安裝 Windows x64 的選用相依性

{
  "pnpm": {
    "supportedArchitectures": {
      "os": ["win32"],
      "cpu": ["x64"]
    }
  }
}

而這個設定會安裝 Windows、macOS 和目前執行安裝的系統架構的選用相依性。它包含 x64 和 arm64 CPU 的人工產物

{
  "pnpm": {
    "supportedArchitectures": {
      "os": ["win32", "darwin", "current"],
      "cpu": ["x64", "arm64"]
    }
  }
}

此外，supportedArchitectures 也支援指定系統的 libc。

pnpm.ignoredOptionalDependencies​

如果一個可選依賴項的名稱包含在此陣列中，它將會被略過。例如

{
  "pnpm": {
    "ignoredOptionalDependencies": ["fsevents", "@esbuild/*"]
  }
}

resolutions​

功能上與 pnpm.overrides 相同，此欄位旨在簡化從 Yarn 的遷移。

resolutions 和 pnpm.overrides 會在套件解析前合併（其中 pnpm.overrides 優先），這在您從 Yarn 遷移時可能很有用，且需要針對 pnpm 調整幾個套件。