私有仓库必须显式声明"type": "vcs"，否则Composer静默忽略；URL须以.git结尾或为SSH格式，且需确保auth.json路径正确、权限600，所有节点须共享同一composer.lock并独立执行install。
私有仓库必须显式声明为 vcs 类型，否则 URL 无效
内网多节点部署时，常见错误是直接在 composer.json 的 repositories 里写裸 Git 地址，比如："https://gitlab.internal/myorg/utils.git"。这会导致 composer require myorg/utils 报错：Could not find a matching version of package myorg/utils。
原因在于 Composer 不会自动推断 URL 是 Git 仓库——它只认配置中明确声明的类型。正确做法是强制指定 "type": "vcs"，且 URL 必须以 .git 结尾（指向裸仓库）：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.internal/myorg/utils.git"
}
]
}
- 若用 SSH，URL 格式应为
git@gitlab.internal:myorg/utils.git，同样需配"type": "vcs" - HTTP Basic 认证凭据不能写在 URL 里（如
https://user:token@gitlab...），必须通过http-basic全局或项目级配置注入 - 多个节点共用同一私有仓库时，所有节点的
~/.composer/auth.json或项目根目录auth.json都要同步凭据，否则部分节点拉包失败
多节点间依赖版本一致性靠 composer.lock 文件驱动，不是靠配置同步
很多人误以为改了 composer.json 里的 repositories 就能“同步依赖”，其实真正起作用的是 composer.lock —— 它锁定了每个包的具体 commit hash、dist URL 和安装路径。只要所有节点执行的是 composer install（而非 update），且共享同一份 lock 文件，就能保证 vendor 内容完全一致。
- CI/CD 流水线中必须把
composer.lock提交进 Git，禁止忽略 - 不同节点若手动运行
composer update，会导致lock文件漂移，进而引发类加载冲突或行为不一致 - 使用
--no-scripts参数可跳过 post-install-cmd 等钩子，避免因节点环境差异（如缺少扩展）导致安装中断
权限粒度控制只能靠 Git 仓库本身，Composer 不提供 RBAC
Composer 本身没有用户角色、读写权限、租户隔离等概念。所谓“不同节点间权限不同”，实际是通过底层 Git 服务实现的：
- 给 Web 节点分配只读 deploy token，限制其只能
git clone --depth 1拉取 tag；给 CI 节点配 full-access token，允许推送 tag 触发发布 - 不要在
composer.json中动态注入 token 或拼接带认证的 URL —— 这会导致凭据泄露到版本库或日志中 - 若需按节点启用/禁用某些私有包，应在部署脚本中用
COMPOSER_ROOT_VERSION或自定义环境变量控制 require 字段的生成逻辑，而不是让 Composer 去“判断权限”
跨节点共享 vendor 目录是反模式，vendor 必须 per-node 独立安装
试图通过 NFS 或 rsync 同步 vendor/ 目录到多个服务器节点，大概率失败。根本原因是：vendor/autoload.php 和 vendor/composer/autoload_static.php 在生成时会固化当前 PHP 版本、扩展可用性、甚至文件系统路径信息。
- PHP 8.2 节点生成的 autoload_static.php，在 PHP 8.1 节点上可能因语法差异（如
match表达式）直接 ParseError - 扩展路径（如
ext-redis的 so 文件位置）在不同节点不一致时，class_exists('Redis')可能返回 false，但 autoload 已注册命名空间，导致运行时报 Class not found - 正确做法：每个节点独立执行
composer install --no-dev --optimize-autoloader -n，并确保php -v与目标 FPM 版本一致（必要时用完整路径调用，如/usr/bin/php8.2 composer install）
最易被忽略的一点：即使所有节点都用相同 PHP 版本，只要 composer.lock 是由不同机器生成的（比如本地开发机生成后提交），仍可能因 realpath 缓存、时区、或 openssl 配置差异，导致 autoload_static.php 中的类映射顺序不一致 —— 最稳妥的方式，是所有节点都从 CI 构建机产出 lock 文件并分发。
