不发布到Packagist，如何使用Composer管理本地开发的私有包？

使用 path 仓库类型最简单有效，Composer 原生支持本地路径作为包源，无需发布或 HTTP 服务；需在 composer.json 中声明 path 类型仓库，路径指向含合法 composer.json 的包目录，name 字段须与 require 一致，推荐用 dev-main 等开发分支版本，并正确定义 autoload 映射，CI/CD 中需切换为真实 Git 仓库。

直接用 path 仓库类型最简单有效

Composer 原生支持本地路径作为包源，无需发布、无需 HTTP 服务，开发调试阶段最轻量。关键在于在项目根目录的 composer.json 中声明 path 类型仓库，并确保路径指向含 composer.json 的包目录（可以是相对或绝对路径）。

• 包目录必须包含合法的 composer.json，且其中 name 字段需与你 require 时写的包名完全一致（如 "myorg/utils"）
• 路径支持通配符，例如 "../../packages/*" 可批量加载多个本地包，但注意匹配顺序和命名冲突
• 执行 composer install 或 composer update 后，Composer 会创建符号链接（Linux/macOS）或复制（Windows），修改本地包代码可立即生效，无需重复 install
• 若遇到 Package myorg/utils not found，优先检查：包目录下 composer.json 的 name 是否拼写一致、是否漏掉 version 字段（dev-main 或 dev-master 是安全默认值）

require 时指定 dev- 分支名而非 stable 版本

本地包没有 Packagist 版本约束，Composer 默认只装 stable 版本，而 path 包通常无稳定 tag，必须显式要求开发分支，否则会报错 Could not find package ... in a version matching ...。

• 在主项目的 composer.json 的 require 中写：

  "myorg/utils": "dev-main"

  （假设包里 composer.json 有 "minimum-stability": "dev" 或未设）
• 如果包使用 master 分支，写 "dev-master"；若已打过 v1.0.0 tag，也可直接写 "1.0.0"，但日常开发更推荐 dev-xxx
• 不建议全局设 "minimum-stability": "dev"，容易意外拉取其他依赖的不稳定版本；应只对特定私有包放宽限制

避免 autoload 冲突和类找不到问题

本地包被 symlink 进 vendor/ 后，自动加载逻辑仍依赖其自身 composer.json 中的 autoload 配置。常见错误是类存在但 Class not found，本质是 PSR-4 映射路径没对上。

• 包的 composer.json 必须正确定义 autoload，例如：

  {
    "autoload": {
      "psr-4": {
        "MyOrg\\Utils\\": "src/"
      }
    }
  }

• 确认包内 src/ 目录结构与命名空间严格对应，比如 src/Helper.php 必须声明 namespace MyOrg\Utils;
• 改完 autoload 配置后，运行 composer dump-autoload（或 composer install）刷新映射，否则不会生效
• 如果主项目也用了相同命名空间前缀，且未隔离，可能引发冲突——此时应统一由私有包管理该命名空间，主项目不要重复声明

CI/CD 和团队协作时需额外处理

path 仓库只在本地有效，CI 环境或新同事 clone 项目后会因路径不存在而失败。这不是 Composer 缺陷，而是设计使然：它本就不是为部署设计的。

• 上线前必须切换为真实仓库（如私有 GitLab、GitHub Private、Satis 或 Toran Proxy），不能靠 path 发布
• 团队内可通过约定路径（如所有人在 ~/projects/myorg-packages/ 下放包），再用绝对路径声明，但可维护性差；更稳妥的是用 Git 仓库 + repositories.type = vcs
• 临时方案：在 CI 脚本中用 git clone 把私有包拉到固定路径，再注入 composer.json，但增加了构建复杂度

真正麻烦的从来不是怎么让本地跑起来，而是怎么让“本地能跑”这件事不污染交付流程——path 是开发加速器，不是部署方案。