必须用 SSH 协议 + 显式仓库声明，否则 Composer 会卡在认证或直接报 401；因 HTTPS 下 GitHub 已弃用密码登录，PAT 无法可靠注入，而 SSH 需密钥对齐、url 含 .git、repositories 为顶层 vcs 类型且包名版本严格匹配。
必须用 SSH 协议 + 显式仓库声明，否则 Composer 会卡在认证或直接报 401
为什么 HTTPS 方式在私有库上大概率失败
Composer 默认走 HTTPS 协议拉取 GitHub 仓库，但私有库在 HTTPS 下不会弹密码框、不读 git config --global credential.helper，而是静默卡住或抛出 Could not fetch https://github.com/xxx/yyy 或 401 Unauthorized。这不是网络问题，是协议层认证机制不匹配。
- GitHub 已弃用密码登录，Personal Access Token（PAT）需带
read:packages或repo权限，且不能硬塞进 URL（如https://token@github.com已被 Git 客户端拒绝） - 全局
composer config -g github-oauth.github.com <token></token>在 CI 环境不可靠——不同项目可能需要不同 token，且无法隔离 - HTTPS +
auth.json虽可行，但容易因 token 过期、权限不足、域名拼写错误（比如写成github.com而非api.github.com）导致失败
SSH 方式怎么配才真正生效
SSH 是更稳定的选择，但“配了密钥”不等于“Composer 能用”，关键在三处对齐：
Investment Researcher Digital Employee
下载
覆盖宏观策略、固收研究、行业公司深度分析、量化因子、大类资产配置、可转债、市场情绪、政策快评、行业景气度追踪等34项核心研究能力，证券研究员的全能数字助手。
- 运行
ssh-keygen -t ed25519 -C "your_email@example.com"生成密钥（建议不设密码，避免 CI 中交互阻塞） - 把
cat ~/.ssh/id_ed25519.pub输出粘贴到 GitHub Settings → SSH and GPG keys - 测试连通性：
ssh -T git@github.com必须返回Hi xxx! You've successfully authenticated - 确保
git clone git@github.com:owner/repo.git能成功执行（不是网页地址，不带.git后缀也不行——git@github.com:owner/repo会失败）
composer.json 里哪些字段不能错
即使 SSH 通了，composer install 仍可能报 Could not find package xxx，问题几乎全出在配置结构上：
-
repositories必须是顶层字段，且类型严格为"type": "vcs"（不是"git"、"package"或嵌套在其他配置下） -
url值必须是完整 SSH 地址："url": "git@github.com:your-org/private-package.git"（注意末尾.git—— 官方文档未强制要求，但实测缺它时git ls-remote可能失败） -
require中的包名必须与私有库根目录composer.json里的"name"字段**逐字符一致**（大小写、斜杠方向、vendor 名拼写都不能差） - 版本必须对应 Git 分支或 tag：
"your-org/private-package": "dev-main"或"v1.0.0"；写"*"或"^1.0"会失败，因为 Composer 无法自动解析私有库的版本元数据
CI 环境和子模块容易忽略的坑
本地能装 ≠ CI 能装。两个高频静默失败点：
- 私有仓库若含 Git 子模块，主仓库克隆成功后，子模块会因无 SSH 密钥单独失败，报
Failed to clone 'xxx': 404—— 需确保子模块也已添加相同 SSH key 到 GitHub，或临时禁用："config": {"git-hooks": false} - CI 中未启动
ssh-agent或未ssh-add私钥，会导致Permission denied (publickey)；推荐用环境变量注入 token +auth.jsonfallback，但前提是先确认 SSH 路径是否真被 Composer 使用（可通过COMPOSER_VERBOSE=1 composer install查看实际执行的git clone命令）
最常被跳过的验证动作：执行 git ls-remote git@github.com:your-org/private-package.git。只要这行命令失败，Composer 就不可能成功——别等 composer install 卡住再排查。
