Composer 依賴下載逾時：如何分辨 dist、原始碼與認證？

Composer 依賴下載逾時，應追查首個失敗傳輸，而非只看最後的安裝錯誤。保存 composer.lock，辨認 dist 壓縮檔或 source 原始碼請求，再分開網絡、憑證與限流，重試原來鎖定的套件集合。

關鍵要點：

• 有鎖檔的 install 和 update 有不同目的。
• dist 與 source 可使用不同主機及認證。
• HTTP 下載與外部程序各有時限設定。
• 傳輸完成不代表外掛、腳本或應用可用。

步驟 1：Composer 依賴下載逾時前，要保護哪些檔案？

保留 composer.json、composer.lock 及可還原的項目副本。記錄原命令、工作目錄、PHP 和 Composer 版本，確認是在本機、容器或遠端建置機執行。憑證留在既有受保護位置，不複製到公開診斷筆記。

php --version
composer --version

有效鎖檔存在時，composer install 使用其中版本；composer update 重新解析並寫入鎖檔，不是等價的下載重試。沒有鎖檔的安裝可解析另一集合，應先確認預期輸入，不稱為固定依賴比較。［3］

也記下開發依賴選擇及下載偏好。同時改 --no-dev、版本約束和 dist/source 偏好，可能取得成功但不同的安裝。對不熟悉的項目先檢查外掛和腳本，因為安裝套件可以執行程式，不只是儲存壓縮檔。

多個應用同時失敗，可先用設備與應用診斷流程找共通問題。知道 Composer 哪段傳輸或安裝失敗後，專項檢查才有對象。

不要先刪掉 vendor 或所有快取，否則下載變多、證據消失，也可能影響使用中的應用。需要新的本機輸出，應在受保護、可棄置副本進行。

步驟 2：首個 Composer curl 錯誤 28 代表甚麼？

從最後安裝失敗向前找受影響套件的首錯，記錄名稱、鎖定版本或修訂、目標角色、取得方式及是否開始傳送位元組。詳細日誌可包含 token 和私人網址，只在本機檢視並遮去敏感資料。

Composer curl 錯誤 28 表示傳輸逾時。官方文件對 HTTP 下載討論 PHP 的 default_socket_timeout，而 process-timeout 限制 Git 複製等外部程序。調高其中一項不會自動處理另一項，不應在未找出操作前一併提高時限。［1］［2］

觀察到的失敗	證據	正確分支
dist 傳輸逾時	壓縮檔主機與鎖定套件	比較該內容請求
source 複製逾時	倉庫和提交修訂	檢查 Git 與程序時限
401 或 403	回應服務及存取要求	核對憑證與權限
429 或明確 API 配額	限額及重試指引	先遵守限流
證書錯誤	PHP/cURL 信任錯誤	修正批准的 CA 設定
解析或腳本失敗	約束或腳本訊息	離開傳輸分支

回應內容傳得慢，不同於服務拒絕憑證；解壓後出錯，也不應寫成壓縮檔主機逾時。保留能顯示階段轉換的上下文，但不公開附帶簽署參數或秘密值的整條網址。

檢查同一執行環境載入的 PHP 設定。IDE、終端和容器可能選擇不同程式及設定檔，可見桌面上的修改未必影響出錯程序。

步驟 3：dist 和 source 為何有不同結果？

dist 通常提供套件修訂的壓縮檔，source 取得原始碼倉庫副本。選項及配置決定下載偏好，各版本是否允許回退也可能不同；看日誌中實際轉移，不假定每次 Composer dist 下載失敗都會接着複製 source。［2］［3］

鎖檔可以描述同一版本的兩種取得形式。私下閱讀相關條目，確定修訂及目標角色。不要手動換下載網址或校驗值來取得另一個壓縮檔；不可信主機上的相似套件不能替代原來內容。

日誌顯示改試 source，就保留兩段結果。原壓縮檔可能失敗但 Git 成功，也可能 Git 因不同認證或傳輸問題失敗；最後安裝成功仍可掩蓋未恢復的 dist 路徑。

Windows 可檢視周邊代理設定，再確認 PHP/cURL 及 Git 繼承甚麼。環境代理及應用配置未必等同瀏覽器路由。修正過期代理屬設定修復，連接 VPN 則是另一項比較。

process-timeout 針對外部程序，不涵蓋全部 HTTP 請求。有持續進度的長複製可受控調整，但需保存原值並說明原因。一直未能連接時，延長等待只會延後相同錯誤。［2］

保持 secure-http 及 TLS 校驗。公司證書攔截需管理員提供批准的 CA 設定；停用驗證後錯誤消失，只代表移除了保護，不是安全恢復。

步驟 4：認證或限流才是真正阻塞嗎？

利用首個 HTTP 回應及倉庫要求分辨認證與傳輸。一個套件的壓縮檔、API 和原始碼倉庫可以需要不同憑證。瀏覽器登入成功，不代表 Composer 有合適 token，或 Git 使用正確身份。

私下核對 auth.json、全局認證設定及環境憑證，確認可存取目標主機及套件。不要輸出完整認證檔或環境，不把 token 放入可複製的公開命令。［1］［2］

遵從 API 限流與重試指引。大量重試、輪換 token 或改 IP 逃避配額不是這裏的網絡路徑診斷；應等待或向服務負責人查詢支援的存取方法。403 可有多個原因，保留上下文，不能無證據下判斷。

套件庫（registry）元資料正常但壓縮檔失敗，應檢查內容主機；私人原始碼失敗，應使用機構要求的網絡及權限。消費 VPN 不能取代內部倉庫入口或公司批准的代理。

套件異常或疑似遭替換時，安裝前停止。重試網絡不能建立信任，應與負責人核對原修訂和服務資料，不為完成命令而壓制警告。

步驟 5：如何重試鎖定下載並確認結果？

在有有效鎖檔、可信而受保護的項目，以下命令可觀察安裝，保留原開發依賴與取得選項。它不是沙箱，外掛及腳本可能執行；跳過它們也會改變受測流程。［3］

composer install -vvv

詳細輸出只在本機檢視。若快取或既有檔案使這次沒有發出內容或倉庫請求，要明確記錄，不能說故障主機已恢復。需要新下載時，先議定可棄置項目副本和獨立輸出，不無計劃清除共用快取。

當證據指出獲准的 dist 內容請求逾時，可讓 AethoVPN 運送相同 Composer 請求，保留 composer.lock、憑證和下載偏好。操作電腦必須是執行 PHP 的那一部：桌面需 Pro 或 Premium，Windows 用官方安裝包，Linux 限 Debian/Ubuntu x64 .deb；Mac 用官網配置在 VPN 客戶端連接。選 App 內可用的鄰近位置、開啟全局模式，重跑原安裝並記錄 dist 完成或轉試 source；改變的是路徑，不是 API 配額、倉庫權限、版本約束或信任要求。

首次比較可以電郵建立帳戶，使用新用戶僅一次的 3 天 Pro 試用。

配合包含原應用請求的連接測試，分清 VPN 連接與套件安裝。容器或遠端程序路由須另行確認，宿主機狀態不是證明。直連有效而 VPN 失敗，就保留可用連接並停止此比較。

確認鎖定版本或修訂透過記錄的方式到達，保持 TLS 及正常流程提供並執行的完整性檢查。沒有通用壓縮檔校驗欄位的套件，不應被說成有統一保證。檢查鎖檔有沒有異常改動；解壓、自動載入生成、外掛、腳本和應用測試各屬後續結果。

Java 項目可追查 Maven 倉庫及套件請求，但不能把 Maven 設定當 Composer 配置。

升級求助提供可公開的套件身份、Composer/PHP 版本、目標角色、取得形式、已遮去敏感資料的首錯、快取和兩條路徑結果。鎖檔意外改動、信任失敗或政策不允許時停止，不任意改版本試運氣。

總結

• 保護鎖檔，交代取得形式。
• 分開壓縮檔、Git 程序、憑證及配額。
• 實際重試請求後才判斷路徑作用。
• 分別報告下載、安裝及應用結果。

常見問題

install 逾時後要執行 composer update 嗎？

應沿用鎖檔及原安裝任務。update 重新解析版本並改變依賴輸入，成功不能解釋原鎖定內容為何失敗；有意的項目更新應分開處理。

process-timeout 控制 curl 下載嗎？

它針對 Git 等外部程序，HTTP 逾時則涉及 PHP 與下載層。先找到失敗操作，再調整相應時限，並還原或記錄設定變化。

dist 失敗，source 為何可以成功？

壓縮檔和倉庫可以用不同主機及認證。source 成功只證明該修訂的這條路徑有效，不代表 dist 主機恢復；應留下回退與首錯證據。

VPN 能處理私人倉庫的 403 嗎？

403 要按回應服務及存取資格判斷。獲准替代路徑可測傳輸，但不會補上缺少的憑證或內容授權；依從倉庫負責人的程序。

如何重試而不透露 auth.json？

讓憑證留在受保護配置，本機查看日誌。分享套件及目標角色時遮去秘密、私人網址和簽署參數，不輸出整個認證檔或環境。

鎖檔不變是否代表下載恢復？

這是輸入核對，未構成傳輸證據。還須確認原套件真正到達，記錄快取、取得形式與適用校驗；安裝腳本及後續測試仍可獨立失敗。

何時應停止重複安裝？

信任失敗、鎖檔異常、明確配額、未授權存取或兩條允許路徑持續同樣失敗時停止。提供遮去敏感資料的首錯與傳輸階段予相關負責人。

來源

1. Composer Troubleshooting — https://getcomposer.org/doc/articles/troubleshooting.md
2. Composer Config — https://getcomposer.org/doc/06-config.md
3. Composer Command-line interface / Commands — https://getcomposer.org/doc/03-cli.md

Sources checked 2026 年 10 月 7 日。

延伸閱讀

• 追查 Maven 套件請求與倉庫設定
• 以 Composer 請求核對 VPN
• Composer 可能讀取的 Windows 代理