私有库需区分包开发与仓库服务：vcs直连适合小团队但构建慢，Satis静态服务稳定可CDN缓存但需手动build；版本依赖Git tag（如v1.2.3），认证凭据仅限600权限auth.json。
私有库不是“建完就能用”，必须分清「包开发」和「仓库服务」两个层面：你写的代码是包，而 Satis 或 Git 本身只是源；不区分这两者，90% 的失败都卡在配置错层。
怎么选私有源类型：vcs 直连 vs satis 静态服务
vcs 类型适合小团队或快速验证：直接在项目 composer.json 的 repositories 里写 Git 地址，不用额外部署服务。但每次 composer install 都要走一次 git clone，CI 构建慢、网络不稳定时容易失败。
satis 是官方推荐的轻量静态服务，适合中大型项目：它把多个私有包的元信息（packages.json）和 ZIP 包预生成到一个 HTTP 可访问目录，客户端只走 HTTP 下载，稳定且可 CDN 缓存。但它不支持实时更新——改了 Git tag 后必须手动运行 php bin/satis build。
常见误判：
- 用
type: "vcs"却把 URL 指向 GitHub 的某个 tag 页面（如https://github.com/org/pkg/tree/v1.0.0），实际应指向仓库根（https://github.com/org/pkg） - 用 satis 却没禁用 Packagist，默认会混源搜索，导致私有包被忽略——必须加
{"packagist.org": false}到repositories数组末尾 - 以为 satis 能代理任意 URL，结果填了
type: "composer"+ 内网域名却没配 HTTPS 或 MIME 类型，packages.json返回 404 或被浏览器解析成 HTML
Git 仓库怎么配才让 Composer 认得版本
Composer 解析 vcs 包时，完全忽略你 composer.json 里的 version 字段。它只看 Git 的 tag 和分支名。
合法 tag 格式只有两种：v1.2.3 或 1.2.3（注意：不是 v1.2，也不是 feature/login）。打 tag 必须带注释并推送：
git tag -a v1.2.3 -m "Release v1.2.3" git push --tags
如果没打 tag，唯一能 require 的是 dev-main（对应 main 分支），但需同时在项目 composer.json 中声明：
"minimum-stability": "dev""prefer-stable": false
否则 Composer 默认跳过所有 dev 版本，报错 Your requirements could not be resolved。
调试命令：composer show vendor/package --all，它会列出当前源识别出的所有版本——如果这里看不到 v1.2.3，说明 tag 没生效或 Git 权限不对。
auth.json 怎么放、怎么写才不翻车
凭据绝不能出现在 composer.json 或 URL 里（如 https://token@github.com/...），这是硬性安全红线。唯一合法位置是 auth.json 文件，且权限必须为 600（Linux/macOS）：
chmod 600 auth.json
文件内容示例（HTTPS Basic Auth）：
{
"http-basic": {
"gitlab.internal.com": {
"username": "deploy",
"password": "xxx"
}
}
}
注意点：
- key 是域名（
gitlab.internal.com），不是完整 URL - SSH 方式不需要
auth.json，但要求部署机已加载对应密钥到ssh-agent，且能ssh -T git@gitlab.internal.com连通 - CI 环境别用
composer config --global写凭据——不同项目可能需要不同 token，应改用环境变量COMPOSER_AUTH注入 JSON 字符串
autoload 映射为什么总报 Class not found
PSR-4 映射路径是相对于私有包自身根目录的，不是主项目。比如你的包结构是：
myorg/utils/
├── composer.json
└── src/
└── MyUtils.php
那么 composer.json 中必须写：
"autoload": {
"psr-4": {
"MyOrg\Utils\": "src/"
}
}
关键细节：
- 命名空间结尾必须是双反斜杠
\（JSON 中写成\\或直接，取决于编辑器转义） -
"src/"是相对路径，不能写成"./src/"或"src"（缺斜杠） - 改完
composer.json后，必须在私有包目录下运行composer dump-autoload，否则新映射不生效 - 如果包是通过 vcs 安装进主项目的
vendor/，它的 autoload 规则由 Composer 在安装时自动合并，无需手动操作
最常被忽略的是：本地开发时用 path 类型做 symlink，但上线部署切回 vcs 后忘记删掉 path 配置，导致 autoload 错乱——path 和 vcs 不能共存于同一 repositories 数组。
