Composer 无法通过 HTTPS 克隆 Bitbucket 私有仓库，因不支持交互式认证；应改用 SSH 协议（需配置密钥）或 Bitbucket App Password（仅 Cloud，需 URL 重写与凭据缓存）。
Composer 无法直接通过 HTTPS 克隆 Bitbucket 私有仓库，必须用 SSH 或配置 OAuth 令牌；HTTPS 方式默认会卡在认证环节，因为 Composer 不弹出密码输入框。
为什么 composer require 拉不下来 Bitbucket 私有包？
Bitbucket 私有仓库默认禁用匿名克隆，而 Composer 的 git 驱动在 HTTPS 协议下不会触发交互式登录（比如输账号密码），导致报错：Failed to execute git clone --mirror 'https://bitbucket.org/xxx/yyy.git' ... fatal: could not read Username for 'https://bitbucket.org': No such device or address。这不是 Composer 配置问题，是协议层限制。
正确做法：改用 SSH 协议 + 全局 Git 配置
这是最稳定、无需每次输密的方案，前提是你的机器已配好 Bitbucket SSH key 并添加到账户中：
- 确认本地 Git 能通过 SSH 访问：
git ls-remote git@bitbucket.org:your-team/your-repo.git应返回 ref 列表 - 在
composer.json中声明仓库时，url字段必须写成 SSH 格式："url": "git@bitbucket.org:your-team/your-repo.git"，不能带https:// - 确保
type是vcs，例如："type": "vcs" - 如果该仓库是作为依赖被 require，且未发布到 Packagist，需在根项目
composer.json的repositories里显式注册
替代方案：用 Bitbucket App Password + HTTPS（仅限 Bitbucket Cloud）
若无法用 SSH（如 CI 环境无密钥管理），可用 App Password 替代账号密码，但必须重写 Git URL 并配置 Git 凭据助手：
- 在 Bitbucket 设置里创建一个 App Password（权限勾选
repository:read） - 把仓库 URL 改成：
https://@bitbucket.org/your-team/your-repo.git - 运行
git config --global credential.helper store，然后手动执行一次git ls-remote https://.../your-repo.git触发凭据缓存 - Composer 会复用 Git 的凭据缓存，后续操作不再报错
- 注意：App Password 不能含特殊字符（如
/、@），否则 URL 解析失败；建议用 Base64 编码或换用 SSH
常见陷阱和验证点
很多问题其实出在细节上：
-
composer.json里的name字段必须和 Bitbucket 仓库路径严格一致（如your-team/your-repo），否则 Composer 找不到匹配包 - 私有仓库的
composer.json必须有合法version（如"dev-main"或带v前缀的 tag），否则 Composer 无法解析稳定性 - 运行
composer install -vvv查看详细日志，重点找Executing command (CWD)行，确认实际执行的是 SSH 还是 HTTPS 命令 - Bitbucket Server（自建版）不支持 App Password，只能走 SSH 或 HTTP Basic + 服务端反向代理透传认证头
SSH 是首选，但得确保部署环境能访问你的密钥；App Password 看似简单，但 URL 编码和凭据缓存时机很容易漏掉。真正在生产环境跑通，往往卡在 Git 层而非 Composer 层。
