私有托管包和仓库的身份验证

您的私有包服务器或版本控制系统可能通过一种或多种身份验证选项来保障安全。为了让您的项目能够访问这些包和代码库，您需要告诉Composer如何通过托管它们的服务器进行身份验证。

认证原则

每当Composer遇到受保护的Composer仓库时，它会首先尝试使用已定义的凭据进行身份验证。如果这些凭据都不适用，它会提示输入凭据并保存（如果Composer能够获取到令牌，也会保存令牌）。

类型	由提示生成？
HTTP基础认证	是
内联HTTP基本认证	否
HTTP 承载	否
自定义标头	否
内联自定义标头	否
gitlab-oauth	是
gitlab令牌	是
github-oauth	是
bitbucket-oauth	是
客户端TLS证书	否
伪造令牌	是的

有时自动认证无法实现，或者您可能希望预先定义认证凭据。

凭证可以存储在4个不同的位置：项目的auth.json中、全局的auth.json中、composer.json自身中，或者COMPOSER_AUTH环境变量中。

每个项目的auth.json中的身份验证

在这种身份验证存储方法中，项目的composer.json文件所在的同一文件夹中会存在一个auth.json文件。你可以通过命令行创建和编辑该文件，也可以手动编辑或创建它。

**注意：确保将auth.json文件放入.gitignore**中，以避免凭证泄露到你的git历史记录中。

全局身份验证凭据

如果你不想为每个参与的项目都提供凭据，那么全局存储凭据可能是个更好的主意。这些凭据会存储在你的Composer主目录下的一个全局auth.json文件中。

命令行全局凭据编辑

对于所有的身份验证方法，都可以通过命令行对其进行编辑；

• http基本认证
• 内联HTTP基本认证
• HTTP 承载
• 自定义标头
• gitlab-oauth
• gitlab令牌
• github-oauth
• bitbucket-oauth
• 伪造令牌

手动编辑全局身份验证凭据

**注意：**不建议手动编辑您的认证选项，因为这可能会导致JSON无效。相反，最好使用命令行。

要手动编辑它，请运行：

php composer.phar config --global --editor [--auth]

有关特定的身份验证实现，请参阅其相应章节；

• http基本认证
• 内联HTTP基本认证
• HTTP 承载认证
• 自定义标头
• 内联自定义标头
• gitlab-oauth
• gitlab令牌
• github-oauth
• bitbucket-oauth
• 客户端TLS证书
• 伪造令牌

手动编辑此文件而不是使用命令行可能会导致无效的json错误。要解决此问题，您需要在编辑器中打开该文件并修复错误。要找到您的全局auth.json的位置，请执行：

php composer.phar config --global home

如果存在全局的auth.json文件，该文件夹将包含此文件。

你可以在你喜欢的编辑器中打开这个文件并修复错误。

composer.json文件本身中的身份验证

**注意：**不建议这样做，因为这些凭据对任何能够访问composer.json的人都是可见的，无论是在通过git等版本控制系统共享时，还是在攻击者获得（读取）您的生产服务器文件的访问权限时。

也可以在每个项目的composer.json的config部分或直接在仓库定义中添加凭据。

使用COMPOSER_AUTH环境变量进行身份验证

**注意：**使用命令行环境变量方法也存在安全隐患。这些凭据很可能会存储在内存中，并且在关闭会话时可能会保存到~/.bash_history（Linux系统）或ConsoleHost_history.txt（Windows系统上的PowerShell）之类的文件中。

为 Composer 提供凭据的最后一个选项是使用 COMPOSER_AUTH 环境变量。这些变量既可以作为命令行变量传递，也可以在实际的环境变量中设置。有关此环境变量用法的更多信息，请参见 此处。

身份验证方法

http-basic

命令行 http-basic

php composer.phar config [--global] http-basic.repo.example.org username password

在上述命令中，配置键http-basic.repo.example.org由两部分组成：

• http-basic是一种认证方法。
• repo.example.org是仓库主机名，你应该用你的仓库的主机名替换它。

手动 http-basic

php composer.phar config [--global] --editor --auth
{
    "http-basic": {
        "example.org": {
            "username": "username",
            "password": "password"
        }
    }
}

内联 http-basic

对于内联HTTP基本认证方法，凭据不会存储在项目中或全局的单独auth.json文件中，而是存储在composer.json或全局配置中，与Composer仓库定义所在的位置相同。

请确保用户名和密码按照RFC 3986（2.1. 百分比编码）进行编码。例如，如果用户名是电子邮件地址，则需要以name%40example.com的形式传递。

命令行内联http-basic

php composer.phar config [--global] repositories.unique-name composer https://username:password@repo.example.org

手动内联http-basic

php composer.phar config [--global] --editor
{
    "repositories": [
        {
            "type": "composer",
            "url": "https://username:password@example.org"
        }
    ]
}

HTTP 承载

命令行HTTP Bearer认证

php composer.phar config [--global] bearer.repo.example.org token

在上述命令中，配置键bearer.repo.example.org由两部分组成：

• bearer 是一种身份验证方法。
• repo.example.org是仓库主机名，你应该用你的仓库的主机名替换它。

手动HTTP Bearer认证

php composer.phar config [--global] --editor --auth
{
    "bearer": {
        "example.org": "TOKEN"
    }
}

自定义标头

对于需要基于标头进行身份验证的私有仓库，请使用自定义HTTP标头进行身份验证。

命令行自定义标头

php composer.phar config [--global] custom-headers.repo.example.org "API-TOKEN: YOUR-API-TOKEN" "X-CUSTOM-HEADER: Value"

在上述命令中，配置键 custom-headers.repo.example.org 由两部分组成：

• custom-headers是一种认证方法。
• repo.example.org是仓库主机名，你应该用你的仓库的主机名替换它。

你可以将多个自定义标头作为单独的参数提供。每个标头必须采用标准的HTTP标头格式"Header-Name: Header-Value"。

手动自定义标头

php composer.phar config [--global] --editor --auth
{
    "custom-headers": {
        "repo.example.org": [
            "API-TOKEN: YOUR-API-TOKEN",
            "X-CUSTOM-HEADER: Value"
        ]
    }
}

内联自定义标头

手动内联自定义标头

对于内联自定义标头身份验证方法，自定义标头作为仓库配置的一部分直接在您的composer.json文件中定义。

php composer.phar config [--global] --editor
{
    "repositories": [
        {
            "type": "composer",
            "url": "https://repo.example.org",
            "options": {
                "http": {
                    "header": [
                        "API-TOKEN: YOUR-API-TOKEN",
                        "X-CUSTOM-HEADER: Value"
                    ]
                }
            }
        }
    ]
}

g it lab-oauth

注意： 要使GitLab认证在私有GitLab实例上生效，gitlab-domains部分还应包含该URL。

命令行 gitlab-oauth

php composer.phar config [--global] gitlab-oauth.gitlab.example.org token

在上述命令中，配置键 gitlab-oauth.gitlab.example.org 由两部分组成：

• gitlab-oauth 是一种认证方法。
• gitlab.example.org 是您的 GitLab 实例的主机名，您应该将其替换为您的 GitLab 实例的主机名，如果您没有自托管的 GitLab 实例，可以使用 gitlab.com。

手动 gitlab-oauth

php composer.phar config [--global] --editor --auth
{
    "gitlab-oauth": {
        "example.org": "token"
    }
}

gitlab-token

注意： 要使 gitlab 认证在私有 gitlab 实例上生效，gitlab-domains 部分还应包含该 URL。

要创建新的访问令牌，请前往您在GitLab上的访问令牌部分（或您的私有实例上的等效URL）并创建新令牌。有关更多信息，另请参阅GitLab访问令牌文档。

手动创建gitlab令牌时，请确保它具有read_api或api权限范围。

命令行 gitlab-token

php composer.phar config [--global] gitlab-token.gitlab.example.org token

在上述命令中，配置键gitlab-token.gitlab.example.org由两部分组成：

• gitlab-token是一种认证方法。
• gitlab.example.org 是您的 GitLab 实例的主机名，您应该将其替换为您的 GitLab 实例的主机名，或者如果您没有自托管的 GitLab 实例，请使用 gitlab.com。

手动 gitlab-token

php composer.phar config [--global] --editor --auth
{
    "gitlab-token": {
        "example.org": "token"
    }
}

github-oauth

GitHub 目前提供两种类型的访问令牌：

• 细粒度令牌
• 令牌（经典版）

这些可以在设置中找到，位于左侧菜单的最底部（开发者选项）。要创建新的访问令牌，请前往GitHub上的令牌设置部分并生成新令牌。

阅读更多关于个人访问令牌的信息。

建议使用细粒度令牌，因为这样你可以更严格地控制可访问的内容。Composer需要对存储库元数据和内容的只读访问权限。

在大多数情况下，一个对公共仓库具有只读访问权限的细粒度令牌可能就足够了。即使没有任何额外权限，这些令牌也能提高你的API速率限制。

在以下情况下，需要额外的权限：

• 你在vcs类型的repositories条目中使用了指向私有存储库的composer.json文件。
• 你正在克隆source，或者通过HTTPS（而非例如SSH）下载私有仓库的dist。

在这些情况下，请创建一个具有“内容”只读访问权限的细粒度令牌。该令牌可以绑定到您的所有仓库、组织的所有仓库，甚至可以限定为仅特定的仓库。

截至2025年11月，细粒度令牌存在限制，即一次只能用于访问单个用户或单个组织的私有仓库。你可以查看GitHub文档了解相关详细信息。如果需要处理来自不同组织的仓库，请确认使用特定目录的身份验证配置是否能满足你的需求。

作为最后的选择，带有repo权限范围的“经典”令牌将授予对您所有私有仓库的广泛访问权限，包括写入权限以及更多权限。权限范围文档包含完整列表。使用此类令牌时请务必谨慎。

无论使用何种类型的令牌，我们都建议使用具有有限生命周期的令牌。这样可以在令牌被盗用的情况下减少风险暴露。

命令行 github-oauth

php composer.phar config [--global] github-oauth.github.com token

在上述命令中，配置键 github-oauth.github.com 由两部分组成：

• github-oauth是一种认证方法。
• github.com 是此令牌适用的主机名。对于 GitHub，您很可能不需要更改此设置。

手动 github-oauth

php composer.phar config [--global] --editor --auth
{
    "github-oauth": {
        "github.com": "token"
    }
}

bitbucket-oauth

BitBucket驱动程序使用OAuth通过BitBucket REST API访问您的私有仓库，您需要创建一个OAuth消费者才能使用该驱动程序，请参考Atlassian的文档。您需要填写一个回调URL以满足BitBucket的要求，但该地址无需指向任何地方，Composer也不会使用它。

命令行 bitbucket-oauth

php composer.phar config [--global] bitbucket-oauth.bitbucket.org consumer-key consumer-secret

在上述命令中，配置键bitbucket-oauth.bitbucket.org由两部分组成：

• bitbucket-oauth 是一种认证方法。
• bitbucket.org 是此令牌适用的主机名。除非你有私有实例，否则无需更改此项。

手动 bitbucket-oauth

php composer.phar config [--global] --editor --auth
{
    "bitbucket-oauth": {
        "bitbucket.org": {
            "consumer-key": "key",
            "consumer-secret": "secret"
        }
    }
}

客户端TLS证书

访问需要客户端TLS证书的私有仓库。

有关全局/项目范围的配置，请参见处理私有包：安全部分。

手动客户端证书

php composer.phar config [--global] --editor --auth
{
    "client-certificate": {
        "repo.example.org": {
            "local_cert": "/path/to/certificate",
            "local_pk": "/path/to/key",
            "passphrase": "MySecretPassword"
        }
    }
}

支持的选项包括local_cert（必填）、local_pk、passphrase。有关这些选项的更多信息，请参见SSL上下文选项。

可省略的选项：

• local_pk：当证书和私钥保存在单个文件中时使用；
• passphrase：用于无密码私钥的情况。

forgejo令牌

注意： 要使锻造（Forge）认证在私有 Forgejo 实例上正常工作，forgejo-domains 部分也应包含该域名。

要创建新的访问令牌，请前往您在Forgejo上的应用程序部分（或您的私有实例上的等效URL）并创建新的访问令牌。有关更多信息，另请参阅Forgejo访问令牌文档。

创建Forgejo访问令牌时，请确保它具有read:repository权限范围。

命令行 forgejo-token

php composer.phar config [--global] forgejo-token.forgejo.example.org username access-token

在上述命令中，配置键 forgejo-token.forgejo.example.org 由两部分组成：

• forgejo-token 是一种认证方式。
• forgejo.example.org 是您的Forgejo实例的主机名，您应该将其替换为您的Forgejo实例的主机名，或者如果您没有自托管的Forgejo实例，请使用codeberg.org。

手动伪造令牌

php composer.phar config [--global] --editor --auth
{
    "forgejo-token": {
        "forgejo.example.org": {
            "username": "forgejo-user",
            "token": "access-token"
        }
    }
}