allow-plugins白名单仅作用于当前项目composer.json,不继承、不跨项目生效,也不被全局配置读取;必须在每个项目中独立声明,且不支持通配符,须精确匹配vendor/name。

allow-plugins 白名单只作用于当前项目,不继承也不跨项目生效
Composer 的 allow-plugins 是项目级配置,写在当前项目 composer.json 的 config.allow-plugins 下,它不会被子目录项目、依赖包或全局配置读取。哪怕你用 composer create-project 生成新项目,新项目也不会自动继承父项目的白名单——每个项目必须独立声明。
常见误操作是把白名单配在全局 ~/.composer/auth.json 或 COMPOSER_HOME/config.json 里,这些位置完全不解析 allow-plugins 字段,Composer 会静默忽略。
- 验证是否生效:运行
composer config allow-plugins,输出应为实际 JSON 对象(如{"symfony/flex": true}),不是null或空值 - 嵌套项目(如 monorepo 中的子包)若需插件,必须各自在自己的
composer.json中重复配置白名单,不能靠“上级目录统一管控” - CI/CD 中若用 wrapper 脚本(如
bin/composer),脚本本身不能覆盖或注入allow-plugins配置;它只能转发命令,白名单仍取决于被执行目录下的composer.json
白名单不控制插件是否“启用”,只控制是否“允许注册”
写 "symfony/flex": true 并不等于 Flex 插件立刻开始工作。它只是授权该包可以调用 PluginInterface 注册逻辑;后续是否真正激活,还取决于包自身的条件判断(比如 extra.symfony.allow-contrib 是否开启、minimum-stability 是否匹配等)。
也就是说,白名单拦不住“注册后不干活”的插件,也拦不住“注册后靠额外配置才干活”的插件。你看到报错说插件被拒绝,大概率是卡在注册阶段;但没报错 ≠ 插件已起效 —— 可能它注册成功了,却因其他配置未满足而跳过执行。
使用 circleci/circleci-cli 和 circleci/orb-tools-orb SDK 来组合和验证 CircleCI Orbs。自动化 orb 打包、使用 conventional-changelog 进行语义化版本控制,并发布到 CircleCI Orb Registry。
- 例如
laravel/pint注册后默认不运行格式化,除非你在scripts里显式调用post-install-cmd或手动执行vendor/bin/pint -
symfony/flex即使进了白名单,若extra.symfony.flex-web-dir缺失或minimum-stability太高,它也可能跳过部分 recipe 加载 - 想确认插件是否真被加载:加
-v参数跑composer install,搜索日志中是否出现Using plugin或Loading package相关行
白名单条目不支持通配符或模糊匹配,必须精确到 vendor/name
Composer 明确不识别 "*"、"vendor/*"、"*/flex" 这类写法。任何含 * 的键都会被忽略,等同于没写。你必须逐个列出完整包名,大小写、短横线、斜杠全部严格匹配。
比如 "symfony/flex" 和 "Symfony/Flex" 是两个不同条目;"laravel/pint" 和 "laravel/pint-cli" 也不能互相替代。一旦拼错一个字符,该插件就会被拦截并报错 The plugin ... is not allowed to be loaded。
- 查真实包名最可靠方式:看 Packagist 页面 URL(如
https://packagist.org/packages/symfony/flex),或运行composer show symfony/flex | head -n1 - 别从 GitHub 仓库名推断——有些包名和仓库名不一致(如
phpunit/phpunit仓库对应包名就是phpunit/phpunit,但laravel/framework的某些工具包可能叫laravel/pint) - 多个插件要分多行写,JSON 格式必须合法:
"symfony/flex": true, "laravel/pint": true(逗号分隔,末尾不能有逗号)
生产环境必须用 --no-plugins,白名单配置在此场景下完全失效
当命令带上 --no-plugins,Composer 会直接跳过所有插件加载逻辑,包括白名单校验、插件注册、事件监听。此时无论你白名单写了多少包,都毫无意义——它根本不会去读 allow-plugins 配置。
这是硬性安全边界,不是可选项。CI/CD 构建、Docker 镜像打包、线上部署,只要涉及不可信输入或自动化流程,就必须强制加上这个 flag。否则白名单再严谨,也挡不住某次 composer update 拉进一个新依赖,其子依赖悄悄带了个未授权插件。
- 正确写法:
composer install --no-plugins --no-scripts --prefer-dist - 错误写法:
composer --no-plugins install(这等价于composer --help,flag 被当成全局选项处理) - 如果你依赖某个插件生成的文件(如 Flex 的
public/index.php),请把它纳入版本控制或构建前脚本,而不是指望生产环境插件自动运行
--no-plugins 下彻底失效)。很多人卡在“明明配了却没用”,问题往往出在这两个地方,而不是语法或权限。

















