详解Composer镜像源同步的版本黑名单过滤机制-composer-PHP中文网

镜像源不提供黑名单过滤功能，仅作元数据和包缓存代理；真正生效的黑名单机制是composer本体的config.audit（如block-insecure）和config.filter（需自建规则源），二者均在本地解析阶段运行，与镜像无关。

详解composer镜像源同步的版本黑名单过滤机制

镜像源本身不提供版本黑名单过滤功能

Composer 镜像（如阿里云、中科大）只是元数据和 ZIP 包的缓存代理，不解析、不修改、不拦截任何包版本信息。所谓“黑名单”，镜像站压根不参与——它不会因为某个版本被 Packagist 标记为 insecure 就拒绝同步，也不会跳过 dev 分支或特定 tag。你看到的“某版本装不上”，99% 是因为镜像还没拉到那个 provider 文件，而不是它主动过滤了。

真正能做版本过滤的只有 Composer 本体，靠的是：config.filter、config.audit 和 replace 这三类配置，它们运行在本地解析阶段，与镜像源无关。

镜像 URL 返回 404 ≠ 主动屏蔽，而是“尚未触发同步”
composer audit 检查 CVE 是读本地 lock + Packagist 元数据，不走镜像逻辑
写 "monolog/monolog": "2.8.1" 锁死版本，无论镜像是否同步该版本，只要它最终能返回 p2/monolog/monolog/2.8.1.json，就能装

真正生效的黑名单机制：config.audit 和 config.filter

Composer 2.0+ 内置的 audit 功能才是你该依赖的“黑名单”。它不是靠镜像，而是靠官方安全公告接口（https://packagist.org/security-advisories）实时比对已安装包是否存在已知漏洞。

启用方式很简单，在 composer.json 中加：

{
  "config": {
    "audit": {
      "block-insecure": true,
      "ignore": {
        "CVE-2021-1234": "已内部修复"
      }
    }
  }
}

注意：block-insecure 设为 true 后，composer update 或 install 时若发现锁文件中含不安全版本，会直接中断并报错 Package monolog/monolog has known security vulnerabilities，不下载、不解压、不写入 vendor。

该机制不依赖镜像源，哪怕你用官方源也能生效
忽略列表（ignore）按 CVE ID 或 GHSA 编号匹配，不是按包名或版本号
它只作用于已解析出的版本，不会影响 Solver 选包过程

config.filter 的高级过滤：需自建规则源

config.filter 是更灵活的黑名单方案，但它要求你提供外部规则源，比如公司内网的 JSON 接口。镜像站不托管、不生成、不分发这类规则。

典型配置如下：

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

{
  "config": {
    "filter": {
      "sources": {
        "internal-filter": {
          "type": "url",
          "url": "https://internal.example.com/filter-list.json"
        }
      }
    }
  }
}

其中 filter-list.json 必须返回标准格式：

[
  {
    "package": "guzzlehttp/guzzle",
    "versions": ["^7.0", "7.5.0"],
    "reason": "存在 DNS rebinding 风险"
  }
]

Composer 会在依赖求解完成后，扫描所有候选版本，匹配到规则即剔除。但关键点在于：这个 JSON 必须能被 Composer 直接 GET 到，且响应头是 Content-Type: application/json。

别指望镜像站帮你托管这个文件；它不在镜像同步范围内
如果内网地址不可达，Composer 会静默跳过该 source，不报错也不提示
过滤发生在 Resolving dependencies 阶段之后，不影响性能，但无法阻止已写入 lock 的旧版本回滚

为什么你看到的“黑名单效果”常是镜像延迟导致的假象

很多人以为“装不上 dev-main 版本”是因为镜像做了过滤，其实只是因为国内镜像默认不拉取 unstable 分支。Packagist 原始元数据里 dev-main 是存在的，但镜像站的同步策略会跳过它——这不是黑名单，是同步白名单（只同步 stable / RC / beta 级别 tag）。

验证方法很直接：

访问 curl -I https://mirrors.aliyun.com/composer/p2/vendor/package/dev-main.json → 返回 404
再访问 curl -I https://repo.packagist.org/p2/vendor/package/dev-main.json → 返回 200

此时你换源、清缓存、重试都没用，因为镜像根本没存。想装 dev-main，只能临时切回官方源：composer config -g repo.packagist composer https://repo.packagist.org/，或者改用 VCS 方式直连 GitHub。

最易被忽略的一点：这种“缺失”不是错误，是设计使然。镜像的目标是加速稳定生产环境部署，不是复刻 Packagist 的全部行为。把镜像当黑名单用，等于把缓存当防火墙——方向错了。