actions/setup-node:版本檔案、自動開啟的快取

Back
Category : News

actions/setup-node 安裝 Node.js 版本、將其加入 PATH、可以還原套件管理器的全域快取,並可以寫入 .npmrc 以進行發佈。從 v6 開始,當 package.json 指定 npm 作為套件管理器時,它會自動快取 npm;而從 v7(目前為 v7.1.0)開始,當設定 registry-url 時不再匯出佔位用的 NODE_AUTH_TOKEN。

Flow of three questions deciding whether setup-node caches, beside the cache key and its rules
setup-node v7 是否執行快取,以及執行時使用的快取金鑰。僅限完全符合,僅在作業成功時才儲存。

大多數工作流程都會從其他地方複製 setup-node 步驟,其中包含沒有人檢查過的 cache: npm 這一行。當主要版本更新時,有些行為就會改變:快取自動開啟、使用 pnpm 的專案在 pnpm 安裝前就失敗,或是 OIDC 發佈因為沒有人設定的 token 而中斷。

其中兩個改變來自快取機制,其規則在 v5 到 v6 之間的兩個月內變更了兩次;另一個來自發佈行為,v7 停止匯出佔位 token。如果你的工作流程早於 v6,請在更新版本前先閱讀快取相關章節。



輸入參數,以及兩個新的快取輸出

表格內容來自 v7.1.0 標籤的 action.yml。會回傳四個輸出值:node-version、cache-hit,以及 v7 新增的 cache-primary-key 和 cache-matched-key,讓後續步驟能確切知道還原了哪個快取項目。快取會在 action.yml 限制為 success() 的 post 步驟中儲存,因此失敗的作業不會為下次執行儲存任何快取。

permissions:
  contents: read
steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    with:
      persist-credentials: false
  - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
    with:
      node-version-file: .nvmrc
      cache: npm
  - run: npm ci
  - run: npm test

Enter fullscreen mode

Exit fullscreen mode

輸入參數 預設值 功能說明
node-version 無 版本規格:24、22.17.1、lts/*、latest。優先於 node-version-file
node-version-file 無 .nvmrc、.node-version、.tool-versions、mise.toml 或 package.json
architecture 執行器的架構 x86、x64 等;除非設定 node-version,否則會被忽略並顯示警告
check-latest false 尋找比快取版本更新但仍符合規格的版本
registry-url 無 寫入 .npmrc,其中的認證行會讀取 NODE_AUTH_TOKEN
scope 無;針對 npm.pkg.github.com 則為存放庫擁有者 限定範圍的 registry 的 scope
token github.token(在 github.com 上) 從 actions/node-versions 下載 Node 建置檔
cache 無 npm、yarn 或 pnpm
package-manager-cache true 設為 false 以停用自動 npm 快取
cache-dependency-path 無 用於快取金鑰的 lockfile 路徑、glob 或清單
mirror 無 Node 二進位檔的替代來源
mirror-token 無 作為 Authorization 標頭傳送給 mirror

輸入與輸出來自 actions/setup-node action.yml v7.1.0 標籤(commit 949feb2413d6458794dcd2491c4babbbce0c15c1),讀取於 2026-11-12。



node-version 或 node-version-file

請設定其中一個。若同時設定兩者,動作會發出警告「Both node-version and node-version-file inputs are specified, only node-version will be used」並忽略檔案。若兩者皆未設定,則使用 PATH 上已有的 Node 版本,該版本會隨執行器映像檔更新而改變。

相對路徑的 node-version-file 會相對於 GITHUB_WORKSPACE 解析,而非步驟的工作目錄;v7.1.0 也接受絕對路徑,因此複合動作可以傳入自己的檔案。對於 package.json,動作會先讀取 volta.node,接著是名為 node 的 devEngines.runtime 項目,然後是 engines.node,最後追蹤 volta.extends。若檔案可讀但無法解析,會記錄警告並繼續使用 PATH 上的 Node;node version file 頁面說明如何將其轉為失敗。

解析時會先檢查執行器工具快取中是否有符合 semver 的版本,接著從 actions/node-versions 下載,再從 nodejs.org 下載。check-latest: true 會在有更新的符合版本時跳過快取版本,但代價是需要下載。



內建快取,以及何時執行

由三個問題決定。若設定了 cache,動作會快取該套件管理器(必須已安裝):在 pnpm 進入 PATH 前使用 cache: pnpm 會導致步驟失敗。若未設定,且 package-manager-cache 保持為 true,則僅在 package.json 的 devEngines.packageManager 或最上層 packageManager 欄位指定 npm 時才快取 npm。否則不會快取任何東西。

它儲存的是套件管理器的全域快取目錄,而非 node_modules,因此 npm ci 仍會執行並建置依賴樹。快取金鑰為 node-cache-<platform>-<arch>-<manager>-<hash>,由 lockfile 產生,還原時必須完全符合:只要改動一個依賴,下次執行就會從頭開始。唯一例外是所有依賴皆由本地管理的 Yarn Berry 專案,可能會以字首還原較舊的項目。

若有多個 lockfile,請將 cache-dependency-path 指向 glob 或清單。關於真實專案中使用快取的實際效益,可參考加快 npm install 中的實測數據。

steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    with:
      persist-credentials: false
  - uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1
    with:
      version: 10
  - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
    with:
      node-version: 24
      cache: pnpm
      cache-dependency-path: |
        apps/web/pnpm-lock.yaml
        apps/api/pnpm-lock.yaml

Enter fullscreen mode

Exit fullscreen mode

快取規則來自 setup-node v7.1.0 的 src/main.ts、src/cache-restore.ts 與 src/cache-utils.ts,讀取於 2026-11-12。



快取規則在兩個月內變更兩次

快取規則在兩個月內變更了兩次。v5 對任何 packageManager 欄位都開啟快取,導致宣告 pnpm 並在之後用 corepack 安裝的專案在 Set up Node.js 階段(corepack 執行前)就失敗(issue 1357)。v6 則將自動快取限制為 npm。

版本 發佈日期 變更內容 建議做法
v4.0.0 2023-10-23 執行環境從 node16 改為 node20 託管執行器無需任何動作
v5.0.0 2025-09-04 執行環境改為 node24;當設定 packageManager 時預設開啟快取 自託管機器需使用 v2.327.1 或更新版本的執行器
v6.0.0 2025-10-14 自動快取限制為 npm;移除 always-auth 輸入參數 明確加入 cache: pnpm 或 cache: yarn;刪除 always-auth
v7.0.0 2026-07-14 移除佔位 NODE_AUTH_TOKEN;新增 cache-primary-key 與 cache-matched-key 輸出;內部改用 ESM 在需要 registry 的地方自行設定 NODE_AUTH_TOKEN
v7.1.0 2026-10-08 支援 mise.toml;支援絕對 node-version-file 路徑;版本驗證與 manifest 擷取重試 無需任何動作

摘自 actions/setup-node 發佈說明以及 README 中的「What’s new in V7」與「Breaking changes」章節,讀取於 2026-11-12。



registry-url、NODE_AUTH_TOKEN 與發佈

action.yml 說明 registry-url 會寫入專案層級的 .npmrc。v7.1.0 的原始碼會將其寫入 $RUNNER_TEMP/.npmrc 並匯出指向該檔案的 NPM_CONFIG_USERCONFIG,因此不會影響你存放庫自己的 .npmrc。寫入的認證行為 //registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}:token 會在發佈時從該步驟的環境中讀取,因此請將 NODE_AUTH_TOKEN 設定在執行發佈的步驟上。

在 v7 之前,若未設定 token,動作會匯出佔位用的 NODE_AUTH_TOKEN=XXXXX-XXXXX-XXXXX-XXXXX。v7 已移除此行為,README 也警告使用 Yarn Classic 或較舊 npm 時,若設定 registry-url 但沒有 token 可能會失敗。npm trusted publishing 完全不需要 token:需使用 npm 11.5.1 或更新版本、設定 id-token: write,並在 npm 上設定與存放庫和工作流程完全符合的 trusted publisher,否則發佈會回傳 E404。

setup-node 文件在所有發佈範例中都設定 package-manager-cache: false,因為持有發佈憑證的作業若有遭污染的快取,可能會導致憑證外洩。請務必比照辦理。

permissions:
  contents: read
  id-token: write
steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    with:
      persist-credentials: false
  - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
    with:
      node-version: 24
      registry-url: https://registry.npmjs.org
      package-manager-cache: false
  - run: npm ci
  - run: npm publish

Enter fullscreen mode

Exit fullscreen mode



遺失檔案、遺失 lockfile 與遺失 pnpm

前兩項已有完整說明頁面,其餘為一行修正。步驟之後、在安裝本身發生的失敗屬於另一類問題:常見的兩種為 npm ci lockfile out of sync 與 no pnpm version is specified。

訊息 原因 修正方式
The specified node version file at: <path> does not exist 輸入路徑與 GITHUB_WORKSPACE 合併後找不到檔案 Node version file does not exist
Dependencies lock file is not found in <workspace>. Supported file patterns: package-lock.json,npm-shrinkwrap.json,yarn.lock 設定了 cache 但根目錄下沒有 lockfile Dependencies lock file is not found
Some specified paths were not resolved, unable to cache dependencies. cache-dependency-path 沒有比對到任何路徑 修正 glob;其路徑相對於 workspace
Unable to find Node version '<spec>' for platform <os> and architecture <arch>. 該平台上沒有符合規格的已發佈建置檔 檢查規格與架構
Unable to locate executable file: pnpm. cache: pnpm 在 pnpm 安裝前就執行 將 pnpm 安裝步驟移到 setup-node 之前



常見問題



actions/setup-node 會快取 node_modules 嗎?

不會。它快取的是套件管理器的全域快取目錄(npm 為 ~/.npm),並以 lockfile 的雜湊值作為金鑰,因此 npm ci 仍會執行並建置 node_modules。setup-node 文件說明原因:全域快取可在不同 Node 版本間重複使用,因此三個版本的 matrix 可以共用同一個快取項目。



為什麼使用 pnpm 時 setup-node v5 會立刻失敗?

v5 只要 package.json 有 packageManager 欄位就會開啟快取,因此宣告 pnpm 的專案會讓動作在任何後續步驟安裝 pnpm 之前就尋找 pnpm(issue 1357)。v6 將自動快取限制為 npm。建議升級,或在 v5 上設定 package-manager-cache: false。



為什麼在 setup-node 設定 registry-url 後,npm OIDC 發佈會失敗?

直到 v6 為止,當你沒有設定 token 時,動作會匯出 NODE_AUTH_TOKEN=XXXXX-XXXXX-XXXXX-XXXXX,而要求移除此預設值的 issue(issue 1440)描述了必須將其清空才能讓 OIDC 發佈正常運作。v7.0.0 已移除此佔位符。在 v7 上,請確認 npm 版本為 11.5.1 或更新,並確認 trusted publisher 與工作流程檔案完全相符。



為什麼 GITHUB_TOKEN 無法從另一個存放庫安裝私人套件?

因為套件僅能被其設定允許的工作流程讀取。setup-node 文件指向套件設定的「Manage Actions access」,在此處加入允許讀取的工作流程所在的存放庫;之後 NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 就能在同組織內的套件上運作。



參考資料

https://dev.to/kalemi/actionssetup-node-version-files-the-cache-that-turns-itself-on-and-publishing-12ll

https://www.worldprogramming.org/posts/actionssetup-node-version-files-the-cache-that-turns-itself-on-and-publishing-sc4l0s