設定#

本章節將說明 composer.json 架構 的 config 部分。

process-timeout#

處理執行逾時時間（以秒為單位），預設為 300（5 分鐘）。若 git clone 等處理程序在 Composer 將其視為執行失敗之前執行的時間。如果您的網路速度較慢或有大量的廠商，您可能需要將此值提高。

若要停用 scripts 中自訂指令的處理逾時，可使用靜態輔助程式

{
    "scripts": {
        "test": [
            "Composer\\Config::disableProcessTimeout",
            "phpunit"
        ]
    }
}

allow-plugins#

預設為 {}，不允許載入任何外掛程式。

自 Composer 2.2.0 起，allow-plugins 選項新增一項安全層，讓您可以在 Composer 執行期間限制哪些 Composer 外掛程式可以執行程式碼。

當首次啟動並未在設定選項中列出的新外掛程式時，Composer 會印出一則警告。如果您以互動方式執行 Composer，它會提示您是否要執行外掛程式。

使用此設定能讓你只允許你信任的套件來執行程式碼。將其設為一個物件，其中套件名稱模式為鍵值。值為 true 代表允許，false 代表不允許，同時抑制進一步的警告和提示。

{
    "config": {
        "allow-plugins": {
            "third-party/required-plugin": true,
            "my-organization/*": true,
            "unnecessary/plugin": false
        }
    }
}

你也可以將組態選項本身設為 false 以不允許所有外掛程式，或設為 true 以允許所有外掛程式執行（不建議）。例如

{
    "config": {
        "allow-plugins": false
    }
}

使用-包含路徑#

預設值為 false。如果設為 true，Composer 自動載入程式也會在 PHP 包含路徑中尋找類別。

偏好的安裝方式#

預設值為 dist，可以設為 source、dist 或 auto。此選項讓你能夠設定 Composer 偏好的安裝方式。另外也可以是一個物件，以套件名稱模式為鍵值，以設定更精細的安裝偏好。

{
    "config": {
        "preferred-install": {
            "my-organization/stable-package": "dist",
            "my-organization/*": "source",
            "partner-organization/*": "auto",
            "*": "dist"
        }
    }
}
  • source 代表 Composer 將會從套件的 source 中安裝套件，若有此來源的話。這通常是套件使用的版本控制系統的 git clone 或等效結帳。如果你想要修復某專案的臭蟲，並直接取得依賴項目的 git clone，這會很有用。
  • auto 是舊有的行為，Composer 會自動針對開發版本使用 source，否則使用 dist。此行為將不再支援。請手動設定 preferred-install。
  • dist（Composer 2.1 起的預設值）代表 Composer 將會從 dist 中安裝，只要能夠的話。這通常會下載一個 zip 檔案，這比複製整個儲存庫快。

注意：順序很重要。比較特定的模式應該要出現在較寬鬆的模式之前。在 global 組態和套件組態中將字串表示法與雜湊組態混合時，字串表示法會被轉譯成 * 套件模式。

稽核#

安全性稽核組態選項

忽略#

一個列出已回報但可以讓稽核指令通過的建議 ID、遠端 ID 或 CVE ID。

{
    "config": {
        "audit": {
            "ignore": {
                "CVE-1234": "The affected component is not in use.",
                "GHSA-xx": "The security fix was applied as a patch.",
                "PKSA-yy": "Due to mitigations in place the update can be delayed."
            }
        }
    }
}

或

{
    "config": {
        "audit": {
            "ignore": ["CVE-1234", "GHSA-xx", "PKSA-yy"]
        }
    }
}

已放棄的#

在 Composer 2.6 中的預設值為 report，在 Composer 2.7 開始的預設值為 fail。定義稽核指令是否回報已放棄的套件，這有三個可能的值

  • ignore 代表稽核指令完全不考慮已放棄的套件。
  • report 代表已放棄的套件會以錯誤的形式回報，但不會讓指令以非零程式碼結束。
  • fail 代表已放棄的套件會讓稽核以非零程式碼失敗。
{
    "config": {
        "audit": {
            "abandoned": "report"
        }
    }
}

自從 Composer 2.7 開始，你可以透過 COMPOSER_AUDIT_ABANDONED 環境變數來覆寫此選項。

使用-父目錄#

當在沒有 composer.json 的目錄中執行 Composer，如果在 Composer 上方的目錄中有一個，Composer 預設會詢問您是否要使用該目錄的 composer.json。

如果您總是想要回答此提示的「是」，您可以將這個設定值設為 true。如果您從來不想被提示，請將該值設為 false。預設值為 "prompt"。

注意：這個設定必須設在您的全域使用者範圍設定中才能生效。例如使用 php composer.phar config --global use-parent-dir true 來設定。

儲存驗證#

提示輸入驗證後要執行的動作，其中之一為：true（總是儲存）、false（不儲存）和 "prompt"（每次都提示），預設為 "prompt"。

GitHub 協定#

預設為 ["https", "ssh", "git"]。これは、github.com から複製するときに使用されるプロトコルのリストで、優先順位は指定された順になります。既定では、git プロトコルが暗号化されていないため、secure-httpが無効になっている場合にのみ git が存在します。オリジンのリモートプッシュ URL で ssh（git@github.com:...）ではなく https を使用する場合は、プロトコルリストを ["https"] のみに設定し、Composer がプッシュ URL を ssh URL に上書きしないようにします。

GitHub OAuth#

ドメイン名と OAuth キーのリスト。たとえば、このオプションの値として {"github.com": "oauthtoken"} を使用すると、oauthtoken を使用して GitHub 上のプライベートリポジトリにアクセスし、その API の IP ベースの低い制限速度を回避できます。Composer は必要に応じて資格情報を求めるメッセージを表示する場合がありますが、手動で設定することもできます。GitHub の OAuth トークンを取得する方法と CLI 構文の詳細については、こちらを参照してください。

GitLab ドメイン#

預設為 ["gitlab.com"]。GitLab サーバのドメインのリスト。gitlab リポジトリタイプを使用する場合に使用されます。

GitLab OAuth#

ドメイン名と OAuth キーのリスト。たとえば、このオプションの値として {"gitlab.com": "oauthtoken"} を使用すると、oauthtoken を使用して gitlab 上のプライベートリポジトリにアクセスできます。注意： パッケージが gitlab.com でホストされていない場合、ドメイン名は gitlab-domains オプションでも指定する必要があります。詳細については、こちらを参照してください。

GitLab トークン#

網域名稱和私密權杖的清單。私密權杖可以是單純字串，也可以包含使用者名稱和權杖的陣列。例如，使用 `{"gitlab.com": "privatetoken"}` 作為此選項的值，將會使用 `privatetoken` 存取 gitlab 上的私人儲存庫。使用 `{"gitlab.com": {"username": "gitlabuser", "token": "privatetoken"}}` 將會使用使用者名稱和權杖，作為 gitlab 部署權杖功能 (https://docs.gitlab.com/ee/user/project/deploy_tokens/)。請注意：如果軟體套件沒有 hosting 在 gitlab.com，則網域名稱也必須以 gitlab-domains 選項指定。權杖必須具有 `api` 或 `read_api` 範圍。詳細資訊也可以在 這裡 找到

gitlab-protocol#

在建立軟體套件金鑰資料的 `source` 值的儲存庫 URL 時，強制使用通訊協定的協定。只能是 `git` 或 `http` 之一。(https 視為 `http` 的同義詞。)對於處理參考私人儲存庫的專案很有幫助，稍後會在 GitLab CI 工作中，使用 GitLab CI_JOB_TOKEN，透過 HTTP 基本驗證，來複製儲存庫。預設情況下，Composer 會為私人儲存庫產生一個 git-over-SSH URL，且僅為公開儲存庫產生 HTTP(S)。

disable-tls#

預設為 `false`。如果設定為 true，所有 HTTPS URL 都會改以 HTTP 嘗試，且不執行網路等級的加密。啟用這個功能有安全風險，不建議這樣做。更好的方法是在 php.ini 中啟用 php_openssl 分機。啟用這個功能會隱含地停用 `secure-http` 選項。

secure-http#

預設為 `true`。如果設定為 true，只有 HTTPS URL 能透過 Composer 下載。如果你真的非常需要透過 HTTP 存取某個東西，你可以停用這個功能，但一般來說，使用 Let's Encrypt 取得免費 SSL 憑證會是一個較好的替代方案。

bitbucket-oauth#

網域名稱和使用者清單。例如，使用 `{"bitbucket.org": {"consumer-key": "myKey", "consumer-secret": "mySecret"}}`。詳情請參閱 這裡。

cafile#

憑證授權檔案在本地端檔案系統中的位置。在 PHP 5.6+，你應該透過 php.ini 中的 openssl.cafile 來設定這個，不過 PHP 5.6+ 應該可以自動偵測你的系統 CA 檔案。

capath#

如果沒有指定 cafile，或是在 cafile 中找不到憑證，就會在 capath 所指的目錄中尋找適當的憑證。capath 必須是經過正確雜湊處理的憑證目錄。

http-basic#

網域名稱和用戶名稱/密碼清單，用於對其進行驗證。例如，使用 {"example.org": {"username": "alice", "password": "foo"}} 做為此選項的值，將讓 Composer 對 example.org 進行驗證。更多資訊可在此處找到 此处。

bearer#

網域名稱和令牌清單，用於對其進行驗證。例如，使用 {"example.org": "foo"} 做為此選項的值，將讓 Composer 使用 Authorization: Bearer foo 標頭對 example.org 進行驗證。

platform#

讓您偽造平台套件（PHP 和延伸）以模仿製作環境或在設定檔中定義目標平台。範例：{"php": "7.0.3", "ext-something": "4.0.3"}。

這將確保無論您在本地執行哪個 PHP 版本，都可以安裝任何 PHP 7.0.3 需求的套件。不過這也表示相依關係不再正確檢查，如果您執行 PHP 5.6，它將會正常安裝，因為它假設為 7.0.3，但之後執行階段會失敗。這也表示如果指定 {"php":"7.4"}，則不會使用任何將 7.4.1 定義為最低的套件。

因此，如果您使用這項功能，建議且安全的做法還包括執行 check-platform-reqs 指令作為部署策略的一部分。

如果相依關係需要您未在本地安裝的延伸，您可以透過傳遞 --ignore-platform-req=ext-foo 至 update、install 或 require 來忽略它。從長遠來看，您應該安裝必要的延伸，因為即使您現在忽略一個延伸，而您在一個月後新增的套件也需要它，您可能會在不知情的情況下在製作環境中引發問題。

如果您已在本地安裝延伸，但並未安裝在製作環境，您可能會想使用 {"ext-foo": false} 人工隱藏它以防 Composer 發現。

vendor-dir#

預設為 vendor。必要的話，您可以將相依關係安裝到其他目錄。$HOME 和 ~ 將在 vendor-dir 及以下所有 *-dir 選項中替換為您的主目錄路徑。

bin-dir#

預設為 vendor/bin。如果專案包含二進檔案，它們將會連結至此目錄。

data-dir#

預設為 Windows 上的 C:\Users\<user>\AppData\Roaming\Composer，遵循 XDG 基本目錄規格的 Unix 系統上的 $XDG_DATA_HOME/composer，以及其他 Unix 系統上的 $COMPOSER_HOME。目前它僅用於儲存舊 composer.phar 檔案，以便能夠回溯到舊版本。另請參閱 COMPOSER_HOME。

cache-dir#

在 Windows 上預設為 C:\Users\<user>\AppData\Local\Composer，macOS 上預設為 /Users/<user>/Library/Caches/composer，遵循 XDG 基本目錄規範的 unix 系統上預設為 $XDG_CACHE_HOME/composer，其他 unix 系統上預設為 $COMPOSER_HOME/cache。儲存 Composer 使用的所有快取。另請參閱 COMPOSER_HOME。

cache-files-dir#

預設為 $cache-dir/files。儲存套件的 zip 檔案。

cache-repo-dir#

預設為 $cache-dir/repo。儲存 composer 類型的儲存庫和 svn、fossil、github 和 bitbucket 類型的 VCS 儲存庫的資料。

cache-vcs-dir#

預設為 $cache-dir/vcs。儲存 VCS 分身以載入 VCS 儲存庫的資料（git/hg 類型），並加快安裝速度。

cache-files-ttl#

預設為 15552000（6 個月）。Composer 快取它下載的所有 dist（zip、tar 等）套件。這些快取在不使用的預設六個月後會清除。此選項允許您微調此持續時間（以秒為單位），或將其設定為 0 以完全停用。

cache-files-maxsize#

預設為 300MiB。Composer 快取它下載的所有 dist（zip、tar 等）套件。當定期執行垃圾回收時，快取將能使用的最大大小為此值。較舊（使用較少的）檔案會優先刪除，直到快取適合為止。

cache-read-only#

預設為 false。是否使用唯讀模式的 Composer 快取。

bin-compat#

預設為 auto。決定要安裝的二進位檔案相容性。如果是 auto，則 Composer 僅在 Windows 或 WSL 上安裝 .bat 代理檔案。如果設定為 full，則會為每個二進位檔案安裝 Windows 的 .bat 檔案和 Unix 系統的腳本。這在您在 linux VM 內執行 Composer，但仍希望在 Windows 主機作業系統中使用 .bat 代理時很有用。如果設定為 proxy，則 Composer 即使在 Windows/WSL 上也會只建立 bash/Unix 風格的代理檔案，而不會建立 .bat 檔案。

prepend-autoloader#

預設為 true。如果為 false，則不會將 Composer 自動載入器新增到現有的自動載入器前面。這有時需要用於修正與其他自動載入器之間的互通性問題。

autoloader-suffix#

預設為 null。設定為非空白字串時，此值將用作產生的 Composer 自動載入器的後綴字元。如果設定為 null，則如果 composer.lock 檔案中存在 content-hash 值，將會使用該值；否則，將會產生一個隨機後綴字元。

optimize-autoloader#

預設為 false。如果為 true，則在傾印自動載入器時總是最佳化。

排序套件#

預設為 false。若為 true，require 指令會在加入新的套件時，根據名稱對 composer.json 中的套件進行排序。

權威類別映射#

預設為 false。若為 true，Composer 自載程式僅會從類別映射載入類別。表示 optimize-autoloader。

APCu 自載程式#

預設為 false。若為 true，Composer 自載程式會檢查 APCu，並在啟用擴充功能時使用它來快取已尋找/未找到的類別。

GitHub 網域#

預設為 ["github.com"]。一個在 GitHub 模式中使用的網域名單。這是用於 GitHub Enterprise 設定。

GitHub 公開主機名稱#

預設為 true。若為 false，就會建立一個用於存取 GitHub API 的 OAuth 令牌，其中有日期而不是機器主機名稱。

使用 GitHub API#

預設為 true。這和特定儲存庫的 no-api 金鑰類似，將 use-github-api 設定為 false 會定義所有 GitHub 儲存庫複製儲存庫時的整體行為，如同使用任何其他 git 儲存庫一樣，而不是使用 GitHub API。但與直接使用 git 驅動程式不同的是，Composer 仍會嘗試使用 GitHub 的 zip 檔案。

安裝時通知#

預設為 true。Composer 允許儲存庫定義通知網址，以便在從該儲存庫安裝套件時收到通知。這個選項允許您停用該行為。

放棄變更#

預設為 false，可以是 true、false 或 "stash"。在非互動模式時，這個選項允許您設定處理未變更更新的預設方式。true 會一直放棄供應商中的變更，而 "stash" 會嘗試暫存並重新套用。如果供應商有修改，請針對 CI 伺服器或部署指令碼使用此選項。

檔案格式#

預設為 tar。覆寫檔案指令碼所使用的預設格式。

檔案目錄#

預設為 .。檔案指令碼所建立的檔案預設目的地。

範例

{
    "config": {
        "archive-dir": "/home/user/.composer/repo"
    }
}

htaccess 保護#

預設為 true。若設定為 false，Composer 就不會在 Composer 主目錄、快取和資料目錄中建立 .htaccess 檔案。

鎖定#

預設為 true。若設定為 false，Composer 就不會建立 composer.lock 檔案，而且在存在的狀況下也會略過它。

平台檢查#

預設為 php-only，只會檢查 PHP 版本。若設定為 true，也會檢查擴充功能的存在性。若設定為 false，Composer 將不會新增和需要一個 platform_check.php 檔案來作為自動載入 bootstrap 的一部分。

secure-svn-domains#

預設為 []。列出應信任/標記為使用安全 Subversion/SVN 傳輸的網域。預設上，svn:// 協定會視為不安全並會擲回錯誤，但是您可以將此組態選項設定為 ["example.org"] 以允許使用該主機名稱上的 svn URL。這比起完全停用 secure-http 是一個較好/較安全的替代方案。

← 儲存庫 | 執行階段 →

找到錯字？這份文件中有些錯誤？分岔並編輯它！