答案是Composer默认将本地路径包视为dev-main分支且不读取其version字段，需在本地包composer.json中显式设version或改用repositories声明path类型仓库并指定dev-main版本。

composer require path/to/local/package 报版本不匹配

这不是路径写错了，而是 Composer 默认把本地路径包当作 dev-main 分支处理，且不自动读取其 composer.json 中的 version 字段。如果你的项目要求 "my/local-package": "^1.2"，但本地包里写的是 "version": "1.0.0"，就会直接失败。

解决方法只有两种：

• 在本地包的 composer.json 里显式加上 "version": "1.2.0"（或符合你约束的任意版本号），再运行 composer require path/to/local/package
• 改用 path repository 方式：在项目根目录 composer.json 的 repositories 段手动声明，例如：

  "repositories": [
    {
      "type": "path",
      "url": "./packages/my-local-package",
      "options": {
        "symlink": true
      }
    }
  ]

  然后 composer require my/local-package:dev-main —— 这样它才会真正读取本地包的元数据

本地包依赖了其他包，但被主项目锁死旧版本

常见现象是：本地包 require 了 guzzlehttp/guzzle:^8.0，但主项目 composer.lock 里还锁着 guzzlehttp/guzzle:7.4.5，执行 composer update 后报冲突。

关键点在于：Composer 不会因为引入本地包就自动升级已有依赖，必须显式触发重算：

• 先确认本地包是否真需要 Guzzle 8 —— 如果只是开发时方便，可降级它的 composer.json 为 "guzzlehttp/guzzle": "^7.4"
• 如果必须用 Guzzle 8，则运行 composer update guzzlehttp/guzzle --with-dependencies，强制连带更新所有直系依赖
• 绝对不要只跑 composer update my/local-package —— 它不会动 guzzlehttp/guzzle，哪怕本地包明确要求它

本地包装进 vendor 后类找不到（autoload 失效）

错误表现是 Class 'MyLocalPackageFoo' not found，即使 vendor/my/local-package 目录存在且结构正确。

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

原因几乎总是 autoload 配置没生效：

• 检查本地包自己的 composer.json 是否有 "autoload": {"psr-4": {"My\LocalPackage\": "src/"}}，且 src/ 路径下确实有对应命名空间文件
• 确认主项目已执行过 composer dump-autoload —— 引入本地包后这步不是自动的
• 如果用了 "symlink": true，确保系统支持符号链接（Windows 需管理员权限启用开发者模式）
• 别信 IDE 缓存：删掉 vendor/composer/autoload_psr4.php 再跑一次 dump-autoload

为什么 composer why-not 不显示本地包的阻塞链

composer why-not 只分析 Packagist 上可索引的包，对 path 类型仓库默认跳过。它查不到“谁在拦住本地包升级”，是因为本地包根本不在依赖图的 SAT 求解范围内 —— Composer 把它当作了“已满足的源”，而不是待解析的约束节点。

所以遇到本地包相关冲突，必须倒推：

• 先用 composer show --tree my/local-package 看它实际加载了哪些子依赖
• 再逐个对这些子依赖跑 composer why-not，比如 composer why-not guzzlehttp/guzzle:^8.0
• 如果本地包本身被其他包 require，而那个包又卡在旧版 Laravel，就得去查那个包的 Packagist 页面，看它是否已支持新环境

本地包不是黑盒，它的约束必须和整个树对齐；一旦脱离这个前提，所有依赖工具都会失语。