Composer如何限制包来源_Composer仓库白名单设置【安全】

先说个结论：Composer 本身并没有设计“仓库白名单”这个配置项。所谓白名单，其实就是关掉默认源、然后手动把你信得过的仓库写明白。别指望加几个镜像地址就能限制包来源——只要默认源还开着，限制就等于零。

至于 repo.packagist.org 为什么不好使？Composer v2+ 对内置源的标识符校验相当严格：唯一的合法键名是 repo.packagist，你要是写成 repo.packagist.org，它会被当成一个普通自定义仓库，根本接管不了默认行为。举个例子：composer config -g repositories.packagist.org url https://mirrors.tuna.tsinghua.edu.cn/composer/ 这样写，默认源该是什么还是什么，完全没用。正确的做法是，先执行 composer config -g repo.packagist false 彻底关闭默认源，再用 repositories.xxx 来显式添加替代项，比如 composer config -g repositories.aliyun type composer 和 composer config -g repositories.aliyun url https://mirrors.aliyun.com/composer/。最后用 composer config -g -l | grep repositories 验证，确保同时出现 repo.packagist=false 和你定义的 repositories.* 条目。

顺手查一下常见失误：很多人写错了键名或者在 CI 里用了 COMPOSER_REPO_PACKAGIST 环境变量——这个变量会直接覆盖默认源设置，务必确认没被设值。

require 的包找不到？不是配置漏了，是包根本不在你声明的仓库里

一旦你把默认源关了，Composer 就变成了一个特别较真的管家——不认识的包，一个也不给你拉。它不会自动探测包属于哪个源，更不会 fallback 到任何你没声明的地址。解决方案其实不复杂：先打开 https://packagist.org/packages/vendor/name，看右上角 “Source” 的指向。如果指向的是 GitHub/GitLab，那就意味着它只存在于 packagist.org，而你已经把这个源关了，所以它自然找不到。临时解决办法是 composer require vendor/name --repository=https://packagist.org，但长期来看，还是得为那个包所在的组织加镜像源。比如 VuePress 用户，就应该加 repositories.vuepress 加上 type composer 和对应镜像 URL。

值得提醒的是，别小看这个检查步骤。从实际项目看，很多人折腾半天以为是配置错了，结果问题就是包压根不在声明的仓库里。

私有包怎么只让某个仓库提供？必须用 type: package

想让私仓只提供 myorg/foo 和 myorg/bar，其他包一概不可见？千万别用 type: composer 或 type: vcs——这两种方式会全量扫描 packages.json，结果就是泛匹配，谁都能进来。唯一靠谱的方式是把私仓声明为 type: package，然后为每个实际提供的包显式写出 name、version、dist 字段。多个包就写多个条目，全部放在 repositories 数组最前面，确保优先级最高。一个典型的配置片段长这样：

{  
  "repositories": [  
    {  
      "type": "package",  
      "package": {  
        "name": "mycorp/utils",  
        "version": "1.2.0",  
        "dist": {  
          "url": "https://artifacts.mycorp.com/utils-1.2.0.zip",  
          "type": "zip"  
        }  
      }  
    }  
  ]  
}

记住，type: package 是最精细的控制方式，没有之一。

插件也要白名单：config.allow-plugins 必须显式声明

Composer 2.2+ 默认禁用了所有第三方插件，而且不支持全局配置。白名单只认当前项目 composer.json 顶层里的 config.allow-plugins 字段。键名必须与插件包的 name 字段完全一致，比如 "phpstan/extension-installer": true，大小写敏感。容易栽跟头的地方有三个：漏掉 vendor 前缀、把类名当成了包名、或者复制了 require 中的别名。查真实插件名最准的方式是 composer show --plugins。

另外，CI/CD 环境下要注意一个问题：白名单不记录在 composer.lock 里，每次 composer install 都会重新读取。版本不一致或者用了 --no-plugins 参数，都会导致白名单认证失败。

注意——真正容易忽视的是三个控制点的优先级和作用域：repositories 数组从上到下扫描，repo.packagist 开关仅全局生效，而 allow-plugins 只对 root package 生效。这三者各自独立，缺一不可，别指望“大概齐”的配置能蒙混过关。