pnpm ERR_PNPM_INVALID_PROXY 怎麼修？先清掉空的代理設定

先辨認錯誤和依賴失敗的邊界#

pnpm issue #13533 記錄了 pnpm v12.0.0-beta.0 的重現方式：執行 HTTP_PROXY= pnpm 後，回報 Invalid proxy URL，並提示檢查 .npmrc、https-proxy、http-proxy、proxy 或環境變數。這不是 lockfile、registry token 或套件版本解析錯誤；要先修正代理設定，才有意義繼續看後面的安裝訊息。

錯誤大致長這樣：

1
ERR_PNPM_INVALID_PROXY
2
Invalid proxy URL:  (could not parse as an authority-bearing URL)

若訊息顯示的是 authentication、registry 404、tarball integrity 或 lifecycle script，請另開一條排查路徑，不要把所有 pnpm install 失敗都歸因於 proxy。

不需要代理時，移除空值而不是設定空字串#

macOS、Linux 和支援 env -u 的 shell 可以在單次安裝中移除代理：

1
env -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY \
2
  -u http_proxy -u https_proxy -u all_proxy \
3
  pnpm install --frozen-lockfile

GitHub Actions 可以把清除動作放在執行 pnpm 的同一個 shell：

1
- name: Install dependencies
2
  shell: bash
3
  run: |
4
    unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
5
    unset http_proxy https_proxy all_proxy
6
    pnpm install --frozen-lockfile

PowerShell 則移除目前 process 的值：

1
$env:HTTP_PROXY = $null
2
$env:HTTPS_PROXY = $null
3
$env:ALL_PROXY = $null
4
pnpm install --frozen-lockfile

這只適用於工作需要「不使用代理」的情況。若公司的網路必須經過 proxy，請設定有效 URL；不要用清除環境變數繞過網路政策。

需要代理時，填入可解析的 URL#

最小格式應包含 scheme、主機和 port：

1
export HTTPS_PROXY='http://proxy.example.com:8080'
2
pnpm install --frozen-lockfile

若 URL 需要帳號密碼，保留在 CI secret 或受控的使用者設定，並將密碼中的 @、#、%、空白等保留字元做 URL encoding：

1
http://build-user:p%[email protected]:8080

不要把含有 token 或密碼的 proxy URL 寫進 repository 的 .npmrc 或 pnpm-workspace.yaml。代理設定本身就是網路目的地，應和 registry credential 分開保護。

找出代理設定從哪裡來#

pnpm 文件把 httpProxy、httpsProxy 和 noProxy 列為 network settings；新版 pnpm 會在 pnpm-workspace.yaml 或全域設定中處理 pnpm-specific settings，.npmrc 仍可能是相容性輸入。先分開檢查設定檔與環境，不要把兩者混成一個值：

1
pnpm --version
2
pnpm config get proxy
3
pnpm config get http-proxy
4
pnpm config get https-proxy
5

6
env | grep -iE '^(http|https|all|no)_proxy='

在 repository 根目錄也可以檢查是否有設定檔宣告代理鍵，但不要把整份可能含有 credential 的檔案貼到 issue：

1
rg -n --hidden --glob '!.git' \
2
  '(^|[[:space:]])(httpProxy|httpsProxy|noProxy|proxy|http-proxy|https-proxy|no-proxy)[:=]' \
3
  pnpm-workspace.yaml .npmrc 2>/dev/null

如果輸出含有帳號、密碼或 token，先遮罩再保存診斷紀錄。真正重要的是知道「哪一層提供空值」，不是把秘密完整印出來。

確認 runner 已經使用修正版#

pnpm 12 RC 0 的 release note 已把 .npmrc、pnpm-workspace.yaml、CLI 和 HTTP_PROXY／HTTPS_PROXY／PROXY／NO_PROXY 的空值視為 unset；proxy=false 在設定檔中也能表達停用代理。這個修正不會替尚未更新的 CI image 自動換版本，所以仍要在失敗的 job 內確認：

1
pnpm --version
2
command -v pnpm
3
pnpm install --frozen-lockfile

pnpm --version 在本機通過，不代表 self-hosted runner、Docker image 或 package manager action 使用同一個 executable。若仍在舊 beta 或未包含修正的版本，先保留 unset workaround，再安排 runner 升級；不要為了繞過 proxy parser 直接刪除 lockfile。

修正版可以解決「空值被誤解析」的程式錯誤，但不會替你決定企業 proxy、noProxy 範圍或憑證輪替策略。安裝成功後再測試 registry authentication、frozen lockfile 和 audit，才能知道下一個失敗是否是另一個問題。

常見問題#