配置

本章将介绍composer.jsonschema的config部分。

进程超时

进程执行的超时时间（以秒为单位），默认值为300（5分钟）。这是像git clone这类进程在Composer认为它们已终止前可以运行的时长。如果您的网络连接较慢或依赖包很大，可能需要延长此时间。

示例：

{
    "config": {
        "process-timeout": 900
    }
}

为单个脚本命令禁用超时

要在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
    }
}

use-include-path

默认为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克隆或类似的检出操作。如果你想对某个项目进行错误修复，并直接获取依赖项的本地git克隆，这会很有用。
• auto 是一种遗留行为，即 Composer 会自动为开发版本使用 source</b1，其他情况下则使用 dist</b2。
• dist（从Composer 2.1开始为默认选项）表示Composer会尽可能从dist进行安装。这通常是一个zip文件下载，比克隆整个代码库更快。

**注意：**顺序很重要。更具体的模式应早于更宽松的模式。在全局和包配置中混合使用字符串表示法与哈希配置时，字符串表示法会被转换为*包模式。

审计

安全审计和版本拦截配置选项。可通过composer audit生成审计报告，更新或require命令结束时会自动报告短格式版本。版本拦截会根据配置，在解析依赖前舍弃被识别为不安全或已废弃的包版本，确保这些版本无法被安装。

忽略

在审计报告和/或版本拦截中被忽略的咨询 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"]
        }
    }
}

带适用范围的详细格式：

详细格式允许您控制忽略是仅适用于审计报告、仅适用于版本拦截，还是两者都适用。apply字段接受：

• audit - 仅在审计报告中忽略（建议不会出现在审计报告中，但软件包在更新期间仍会被阻止）
• block - 仅在版本阻止时忽略（包可在更新期间使用，但安全建议仍会出现在审计报告中）
• all - 在审计报告和版本拦截期间忽略（默认行为）

{
    "config": {
        "audit": {
            "ignore": {
                "CVE-1234": {
                    "apply": "audit",
                    "reason": "Not applicable to us, so don't report, but still want to make sure we don't use this version in updates."
                },
                "GHSA-xx": {
                    "apply": "block",
                    "reason": "Workaround applied, can only fix next week, allow during updates but still report in audits"
                },
                "PKSA-yy": {
                    "apply": "all",
                    "reason": "False report, Ignore completely in all contexts"
                }
            }
        }
    }
}

所有格式可以在同一配置中混合使用。

abandoned

自Composer 2.7起默认值为fail（在新增此选项的Composer 2.6中，默认值为report）。它定义了审计报告是否以及如何报告已废弃的包。有三个可能的值：

• ignore表示审计报告完全不考虑已废弃的包。
• report表示废弃的包会被报告为错误，但不会导致composer audit命令返回非零退出代码。
• fail表示被丢弃的包会导致审计命令以非零退出代码失败。

请注意，这仅适用于审计报告，此设置不会影响对不安全包版本的拦截。要配置对废弃包的拦截，请参阅block-abandoned选项。

{
    "config": {
        "audit": {
            "abandoned": "report"
        }
    }
}

自Composer 2.7起，可通过COMPOSER_AUDIT_ABANDONED环境变量覆盖此选项。

自Composer 2.8起，可通过--abandoned命令行选项覆盖该选项，此选项会同时覆盖配置值和环境变量。

ignore-abandoned

一份废弃包名称列表，这些包在审计报告和/或版本拦截中会被忽略。这使你能够选择那些尽管已处于废弃状态但你仍想继续使用的包。

带原因的简单格式：

{
    "config": {
        "audit": {
            "ignore-abandoned": {
                "acme/*": "Work scheduled for removal next month.",
                "acme/package": "Transitive dependency but unreachable and not in active use within our project context."
            }
        }
    }
}

无原因的简单格式：

{
    "config": {
        "audit": {
            "ignore-abandoned": ["acme/*", "acme/package"]
        }
    }
}

带适用范围的详细格式：

详细格式允许您控制忽略是仅适用于审计报告、仅适用于版本拦截，还是两者都适用。apply字段接受：

• audit - 仅在审计报告中忽略（软件包不会出现在审计报告中，但如果启用了block-abandoned，则在更新期间仍会被阻止）
• block - 仅在版本阻止时忽略（即使启用了block-abandoned，包在更新期间仍可使用，但仍会出现在审计报告中）
• all - 忽略审计报告和版本拦截（默认行为）

{
    "config": {
        "audit": {
            "ignore-abandoned": {
                "acme/package": {
                    "apply": "block",
                    "reason": "Allow during updates but still report as abandoned"
                },
                "vendor/*": {
                    "apply": "all",
                    "reason": "We maintain these packages internally"
                }
            }
        }
    }
}

所有格式可以在同一配置中混合使用。

ignore-severity 默认为[]。这是一个在审计报告和/或版本阻塞中被忽略的严重性级别列表。 简单格式：# audit - 仅在审计报告中忽略（具有此严重性的建议不会出现在审计报告中，但包在更新期间仍会被阻塞）

默认为[]。这是一个严重性级别列表，在审计报告和/或版本拦截时会被忽略。

简单格式：

{
    "config": {
        "audit": {
            "ignore-severity": ["low", "medium"]
        }
    }
}

带适用范围的详细格式：

详细格式允许您控制忽略是仅适用于审计报告、仅适用于版本拦截，还是两者都适用。apply字段接受：

• audit - 仅在审计报告中忽略（此严重级别的公告不会出现在审计报告中，但更新期间仍会阻止相关包）
• block - 仅在版本阻断时忽略（包可在更新期间使用，但具有此严重性的公告仍会出现在审计报告中）
• all - 在审计和拦截期间均忽略（默认行为）

{
    "config": {
        "audit": {
            "ignore-severity": {
                "low": {
                    "apply": "all"
                },
                "medium": {
                    "apply": "block"
                }
            }
        }
    }
}

所有格式可以在同一配置中混合使用。

ignore-unreachable

默认为false。在执行composer audit时是否应忽略不可访问的仓库。如果你在无法访问所有仓库的环境中运行该命令，这可能会有所帮助。此设置不适用于版本拦截或在compoder audit命令以外的其他地方生成的审计报告。

{
    "config": {
        "audit": {
            "ignore-unreachable": true
        }
    }
}

block-insecure

默认值为true。如果为true，则任何受安全公告影响的包版本都将被阻止，且在执行composer update/require/delete命令期间无法使用，除非忽略这些安全公告。如果启用了block-abandoned，版本阻止还将禁止使用已废弃的包。

{
    "config": {
        "audit": {
            "block-insecure": false
        }
    }
}

block-abandoned

默认为false。如果为true，则在composer update/required/delete命令期间，任何废弃的包都不能使用。仅当未通过将block-insecure设置为false来禁用版本阻塞时才适用。

{
    "config": {
        "audit": {
            "block-abandoned": true
        }
    }
}

use-parent-dir 当在没有composer.json的目录中运行Composer时，如果其上级目录中存在composer.json，Composer默认会询问你是否要使用该目录下的composer.json。 如果你希望始终对该提示回答“是”，可以将此配置值设为true。如果不想被提示，将其设为false。默认值为”prompt”。 注意：此配置必须在你的全局用户配置中设置才能生效。例如，可使用php composer.phar config —global use-parent-dir true进行设置。

当在没有composer.json的目录中运行Composer时，如果其上级目录中存在该文件，Composer默认会询问你是否要使用上级目录中的composer.json。

如果你总是想对这个提示回答“是”，可以将此配置值设置为true。如果不想被提示，将其设置为false。默认值为"prompt"。

**注意：**此配置必须在您的全局用户范围内配置中设置才能生效。例如，使用php composer.phar config --global use-parent-dir true进行设置。

store-auths

提示进行身份验证后该怎么做，选项之一：true（始终存储）、false（不存储）和"prompt"（每次询问），默认值为"prompt"。

github协议

默认值为["https", "ssh", "git"]。这是从github.com克隆时要使用的协议列表，按优先级排序。默认情况下，git会存在，但仅当secure-http被禁用时才会如此，因为git协议是未加密的。如果你希望你的源远程推送URL使用https而不是ssh（git@github.com:...），那么将协议列表设置为仅包含["https"]，Composer就会停止将推送URL覆盖为ssh URL。

github-oauth

域名和OAuth密钥的列表。例如，使用{"github.com": "oauthtoken"}作为此选项的值，将使用oauthtoken访问GitHub上的私有仓库，并规避其API基于IP的低速率限制。Composer可能会在需要时提示输入凭据，但这些凭据也可以手动设置。有关如何获取GitHub的OAuth令牌以及命令行界面语法的更多信息，请参见此处。

gitlab-域名

默认为["gitlab.com"]。这是GitLab服务器的域名列表。如果您使用gitlab存储库类型，则会用到此列表。

g it lab-oauth

域名和oauth密钥的列表。例如，使用{"gitlab.com": "oauthtoken"}作为此选项的值，将使用oauthtoken访问gitlab上的私有仓库。请注意：如果包不是托管在gitlab.com，那么域名也必须通过gitlab-domains选项指定。更多信息也可以在此处找到。

gitlab-token

域名和私人令牌的列表。私人令牌可以是简单字符串，也可以是包含用户名和令牌的数组。例如，将{"gitlab.com": "privatetoken"}用作此选项的值时，将使用privatetoken访问gitlab上的私人仓库。使用{"gitlab.com": {"username": "gitlabuser", "token": "privatetoken"}}将同时使用用户名和令牌来实现gitlab的部署令牌功能（https://docs.gitlab.com/ee/user/project/deploy_tokens/）。请注意：如果包并非托管在gitlab.com，那么还必须通过[`gitlab-domains`](config.html#gitlab-domains)选项指定域名。该令牌必须具有api或read_api权限范围。更多信息也可参见此处。

gitlab协议 为包元数据的source值创建仓库URL时强制使用的协议。可为git或http之一（https被视为http的同义词）。当处理引用私有仓库的项目时很有帮助，这些项目之后会在GitLab CI作业中使用HTTP基本认证和GitLab CI_JOB_TOKEN进行克隆。默认情况下，Composer会为私有仓库生成基于SSH的git URL，仅为公共仓库生成HTTP(S) URL。

创建包元数据的source值的仓库URL时强制使用的协议。可以是git或http中的一种（https被视为http的同义词）。这在处理引用私有仓库的项目时很有用，这些项目之后会在GitLab CI作业中使用GitLab CI_JOB_TOKEN通过HTTP基本认证进行克隆。默认情况下，Composer会为私有仓库生成基于SSH的git URL，仅为公共仓库生成HTTP（S）URL。

forge jo-域

默认为["codeberg.org"]。这是一个Forgejo服务器的域名列表。如果您使用forgejo存储库类型，则会用到此列表。

forgejo令牌

一系列域名以及用于对其进行身份验证的用户名/访问令牌。例如，使用{"codeberg.org": {"username": "forgejo-user", "token": "access-token"}}作为此选项的值，Composer 将能够对 codeberg.org 进行身份验证。请注意：如果包并非托管在 codeberg.org，那么还必须通过forgejo-domains选项指定域名。更多信息也可在此处找到。

禁用TLS

默认值为false。如果设置为true，所有HTTPS URL都将尝试改用HTTP，并且不执行网络级加密。启用此功能存在安全风险，不建议这样做。更好的方法是在php.ini中启用php_openssl扩展。启用此功能将隐式禁用secure-http选项。

secure-http 默认值为true。如果设为true，Composer仅允许通过HTTPS URL进行下载。如果确实绝对需要对某些内容进行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，或者在其中未找到证书，则会在capath指向的目录中搜索合适的证书。capath必须是正确哈希处理过的证书目录。 http-basic# 用于进行身份验证的域名以及用户名/密码列表。例如，将此选项的值设为{“example.org”: {“username”: “alice”, “password”: “foo”}}，Composer就能对example.org进行身份验证。点击此处查看更多信息。

默认值为true。如果设置为true，那么只有HTTPS URL允许通过Composer下载。如果你确实绝对需要对某些内容进行HTTP访问，那么可以禁用此设置，但使用Let’s Encrypt获取免费的SSL证书通常是更好的选择。

bitbucket-oauth

域名和消费者的列表。例如，使用{"bitbucket.org": {"consumer-key": "myKey", "consumer-secret": "mySecret"}}。在此处了解更多信息。

咖啡馆

证书颁发机构文件在本地文件系统上的位置。在PHP 5.6及以上版本中，您更应该通过php.ini中的openssl.cafile来设置，不过PHP 5.6及以上版本应该能够自动检测您的系统CA文件。

证书路径

如果未指定cafile，或者在其中未找到证书，则会在capath所指向的目录中搜索合适的证书。capath必须是一个正确哈希处理的证书目录。

http-basic

一系列域名以及用于对其进行身份验证的用户名/密码。例如，将{"example.org": {"username": "alice", "password": "foo"}}用作此选项的值，Composer将能够对example.org进行身份验证。更多信息可在此处查看。

bearer

一个域名列表和用于对其进行身份验证的令牌。例如，使用{"example.org": "foo"}作为此选项的值，Composer将使用Authorization: Bearer foo头部对example.org进行身份验证。

平台

允许你伪造平台包（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、install或require时，通过添加—ignore-platform-req=ext-foo来忽略它。不过从长远来看，你应该安装所需的扩展，因为如果你现在忽略了一个扩展，而一个月后添加的新包也需要它，你可能会在不知不觉中给生产环境带来问题。

如果你在本地安装了某个扩展，但在生产环境中没有安装，你可能希望通过{"ext-foo": false}来人为地让Composer隐藏它。

供应商目录

默认为vendor。如果需要，您可以将依赖项安装到不同的目录中。$HOME和~将在供应商目录以及下面所有的*-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。

缓存目录

在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-dir/files。用于存储包的zip归档文件。

缓存仓库目录

默认为$cache-dir/repo。用于存储composer类型以及svn、fossil、github和bitbucket类型的VCS仓库的仓库元数据。

cache-vc s-目录

默认为$cache-dir/vcs。存储版本控制系统（VCS）克隆，用于加载git/hg类型的版本控制系统仓库元数据，并加快安装速度。

缓存-文件-ttl

默认为15552000（6个月）。Composer会缓存其下载的所有发行版（zip、tar等）包。默认情况下，这些包在6个月未使用后会被清除。此选项允许你调整此持续时间（以秒为单位），或通过将其设置为0来完全禁用它。

cache-files-maxsize 默认值为300MiB。Composer会缓存其下载的所有发行版（zip、tar等）包。当定期运行垃圾回收时，这是缓存能够使用的最大大小。较旧（较少使用）的文件将被优先删除，直到缓存大小符合限制。

默认值为300MiB。Composer会缓存其下载的所有分布式（zip、tar等）包。当定期运行垃圾回收时，这是缓存能够使用的最大大小。较旧（较少使用）的文件将被优先删除，直到缓存符合大小限制。

cache-read-only 默认值为false。是否以只读模式使用Composer缓存。

默认值为false。是否以只读模式使用Composer缓存。

bin-compat

默认值为auto。它决定了要安装的二进制文件的兼容性。如果设为auto，那么Composer仅在Windows或WSL系统上安装.bat代理文件。如果设为full，则会为每个二进制文件安装适用于Windows的.bat文件和适用于基于Unix的操作系统的脚本。这在以下情况中尤其有用：你在Linux虚拟机中运行Composer，但仍希望.bat代理可用于Windows主机操作系统。如果设为proxy，即使在Windows/WSL系统上，Composer也只会创建bash/Unix风格的代理文件，而不会创建.bat文件。

自动装载 > # < /

默认为true。如果为false，Composer自动加载器将不会添加到现有自动加载器之前。这在某些情况下是解决与其他自动加载器的互操作性问题所必需的。

自动加载器后缀

默认为null。当设置为非空字符串时，此值将用作生成的Composer自动加载器的后缀。如果设置为null，则会使用composer.lock文件中的content-hash值（如果可用）；否则，将生成一个随机后缀。

optimize-autoloader

默认值为false。如果为true，则在生成自动加载器时始终进行优化。

sort-packages

默认为false。如果为true，则添加新包时，require命令会按名称在composer.json中对包进行排序。

classmap-authoritative

默认值为false。如果为true，Composer自动加载器将仅从类映射加载类。这意味着启用了optimize-autoloader。

apcu-autoloader

默认为false。如果为true，则当扩展启用时，Composer自动加载器将检查APCu，并使用它来缓存已找到/未找到的类。

github-domains

默认为["github.com"]。这是在github模式下使用的域名列表。用于GitHub企业版设置。

github-expose-hostname

默认为true。如果为false，则为访问github API而创建的OAuth令牌将包含日期而非机器主机名。

use-github-api

默认为true。与特定仓库上的no-api键类似，将use-github-api设置为false会定义所有GitHub仓库的全局行为，即像克隆任何其他git仓库一样克隆该仓库，而不是使用GitHub API。但与直接使用git驱动程序不同，Composer仍会尝试使用GitHub的zip文件。

安装时通知

默认值为true。Composer允许仓库定义通知URL，以便每当安装该仓库中的包时，仓库都能收到通知。此选项可让你禁用该行为。

discard-changes 默认值为false，且可以是true、false或”stash”中的任意一个。此选项允许你在非交互模式下设置处理未提交更新的默认方式。true会始终丢弃供应商中的更改，而”stash”会尝试暂存并重新应用更改。如果你倾向于修改供应商，可在CI服务器或部署脚本中使用此选项。 archive-format# 默认值为tar。用于覆盖归档命令使用的默认格式。 archive-dir# 默认值为.。是归档命令创建的归档文件的默认目标位置。

默认为false，可以是true、false或"stash"中的任意一个。此选项允许你在非交互模式下设置处理脏更新的默认样式。true将始终丢弃供应商中的更改，而"stash"将尝试暂存并重新应用。如果你倾向于修改供应商，可在CI服务器或部署脚本中使用此选项。

存档格式

默认为tar。覆盖归档命令使用的默认格式。

归档目录

默认为.。这是archive命令创建的归档文件的默认目标位置。

示例：

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

htaccess-protect

默认为true。如果设置为false，Composer将不会在Composer主目录、缓存目录和数据目录中创建.htaccess文件。

lock

默认值为true。如果设置为false，Composer将不会创建composer.lock文件，并且如果存在该文件，也会忽略它。

platform-check

默认值为php-only，它只检查PHP版本。设置为true时也会检查扩展是否存在。如果设置为false，Composer将不会创建platform_check.php文件，也不会在自动加载器引导过程中要求该文件。

secure-svn-domains

默认值为[]。列出应被信任/标记为使用安全Subversion/SVN传输的域。默认情况下，svn://协议被视为不安全并会抛出错误，但你可以将此配置选项设置为["example.org"]，以允许在该主机名上使用svn URL。这是完全禁用secure-http的一种更好/更安全的替代方案。

更新后升级

xxxxxxxxxx php composer.phar config -g repo.packagist.org falsebashell

allow-missing-requirements

默认为false。如果存在任何缺失的需求（锁文件未与composer.json中的最新更改保持同步），则会忽略install过程中的错误。

以最小更改进行更新

默认值为false。如果设置为true，Composer在更新期间将仅对传递依赖项进行绝对必要的更改。也可以通过COMPOSER_MINIMAL_CHANGES=1环境变量进行设置。