Composer repositories canonical 设置怎样影响私有包解析

Composer 解析依赖时，repositories 的顺序和 canonical 设置会直接影响“同名包到底从哪个仓库来”。如果私有仓库里有 acme/payment，公共仓库里也出现了同名包，问题往往不是 autoload 没更新，而是 Composer 已经在更靠前的 canonical 仓库找到这个包，停止继续搜索，或者私有仓库根本没有被配置为预期的来源。

Composer 官方地址：https://getcomposer.org/

排查顺序建议固定为：先看 repositories 的声明顺序，再确认 canonical 是否符合来源边界，接着用 composer show 和 composer why 观察当前解析结果，最后才考虑 only、exclude 或锁文件调整。Composer 2.x 默认仓库是 canonical，公共 Packagist 通常作为隐式的最后仓库加入。

先把仓库顺序当成解析规则

Composer 官方对 canonical repository 的描述可以概括为：解析某个包时，从顶层仓库开始查找；如果仓库不包含这个包，才继续向下一个仓库查找；一旦某个仓库包含该包，canonical 规则就可能让查找在这里结束。这里的“顶层”是 composer.json 中靠前的仓库，而不是网络上版本号最高的仓库。

这意味着下面的顺序表达了一个明确的来源策略：企业内部仓库优先，公共仓库只负责没有内部镜像的包。

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://packages.example.internal"
    },
    {
      "type": "composer",
      "url": "https://packages.example.org"
    }
  ],
  "require": {
    "acme/payment": "^2.4"
  }
}

这个片段只用于说明配置关系，域名是示例地址，不代表可直接访问的真实仓库。实际项目中，先确认私有仓库返回的包名与版本元数据，再判断它是否已经被第一条 repository 命中。

canonical 为什么会让私有包解析结果不同

Composer 2.x 默认将仓库视为 canonical。对私有包来说，这个默认值通常是保护措施：如果私有仓库中的 acme/payment 已经命中，Packagist 上后来出现的同名包就不会因为版本号更高而接管解析。否则，团队以为自己安装的是内部包，实际可能拿到另一个来源，风险和排查成本都会上升。

如果某个仓库只是“候选来源”，希望 Composer 在它找到包后仍继续检查后面的仓库，可以显式设置 canonical: false：

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://packages.example.internal",
      "canonical": true
    },
    {
      "type": "composer",
      "url": "https://packages.example.org",
      "canonical": false
    }
  ]
}

不要把 canonical: false 当成“私有仓库优先”。它表达的是：这个仓库命中后仍允许后面的仓库参与查找和版本选择。对于内部包、合规包或必须固定来源的包，通常更应该保留 canonical，并通过仓库内容和权限保证来源唯一。

先用 Composer 命令看当前结果

配置修改前，先把当前解析结果留一份可比较的记录。composer show 可以查看已安装包的版本和来源信息；composer why 用来回答“哪个依赖要求了这个包”。命令本身不会替你证明仓库来源策略正确，所以重点是把名称、版本和 source/dist 指向放在一起看。

# 查看目标包的已安装版本、来源和描述，先确认当前锁定了什么。
composer show acme/payment --all

# 找出是谁引入目标包，区分直接 require 与传递依赖。
composer why acme/payment

# 列出根项目声明的仓库，确认顺序和过滤配置。
composer config repositories --list

如果命令显示的包名、版本或 source/dist 指向与预期不一致，先回到 composer.json 检查仓库顺序和包名大小写。若配置已经正确但结果仍不变，再确认是否只是 composer.lock 保留了旧解析结果；锁文件调整应当在审查变更范围后进行，而不是一上来删除它。

一个实用的判断表如下：

用 only 或 exclude 缩小仓库负责范围

当一个仓库只应该提供少数内部包时，单靠顺序和 canonical 还不够直观，可以用 only 或 exclude 做包名过滤。官方文档支持通配符，适合把供应边界直接写进项目配置。

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://packages.example.internal",
      "only": [
        "acme/*",
        "company/audit"
      ]
    }
  ]
}

上面的配置表达“这个仓库只负责 acme/ 命名空间和一个明确包”。如果内部仓库中混有不应该被项目使用的包，也可以采用排除写法：

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://packages.example.internal",
      "exclude": [
        "acme/experimental"
      ]
    }
  ]
}

only 与 exclude 是仓库级别的过滤规则，不是替代 require 版本约束的快捷写法。最终仍要用项目根包的 require、锁文件和依赖链共同决定可安装结果。过滤规则越精确，后续维护者越容易解释“为什么这个仓库没有提供某个包”。

整理一套不容易误判的上线配置

在开发机上能安装，不等于生产环境的来源边界已经固定。提交配置前可以按下面顺序做一次人工复查：

1. 把内部包的完整名称列出来，确认仓库元数据中的 name 与 require 完全一致。
2. 把私有仓库放在公共仓库之前，对必须来自内部的仓库保留 canonical 默认行为。
3. 一个仓库负责的包较少时，用 only 明确命名空间；需要排除少数包时再用 exclude。
4. 用 composer show 和 composer why 记录升级前后的版本、来源和依赖链。
5. 审查 composer.lock 的差异，只更新预期包，保留可回滚的提交。

如果团队确实需要多个仓库共同参与版本选择，应该把 canonical: false 写成经过评审的例外，并说明哪些包允许这样解析。对所有仓库一律关闭 canonical，会让安全边界和来源审计变得模糊。

几个容易混淆的问题

canonical 会不会重新生成 autoload 文件？

不会。canonical 影响的是依赖解析时的仓库查找策略，autoload 生成属于安装或更新后的包文件映射。两者可能在同一次 Composer 操作中先后发生，但排查时要分开看。

把仓库放第一就一定能拿到私有包吗？

不一定。仓库还必须能返回目标包、名称和兼容版本；认证失败、包元数据缺失、包名写错或过滤规则排除了它，都会让“顺序正确”仍然无法命中。

为什么改了 canonical 还看不到变化？

先确认修改的是根项目的 composer.json，再看执行命令是否更新了目标包。若锁文件仍锁定原来源，配置变化可能不会自动改写现有安装结果。

only 和 exclude 应该选哪个？

默认只允许一组命名空间时优先用 only，它的边界更容易读；已有仓库负责范围很大、只需剔除少数包时再用 exclude。两者都应配合仓库顺序和 canonical 复查。

把 Composer 仓库当成“有顺序的包来源”来排查，通常比反复重建 vendor 更快。先保证私有包来源可见，再用 canonical 固定来源边界，最后用过滤规则和锁文件差异收敛变更范围，遇到同名包时就能较快判断问题究竟出在仓库、解析策略还是安装结果。