Bitbucket私有仓库需在composer.json中声明vcs类型并使用带.git后缀的HTTPS地址，如"https://bitbucket.org/your-org/internal-sdk.git"；同时须配置应用密码至auth.json，认证域严格为bitbucket.org。
composer.json 里怎么写 Bitbucket 私有仓库地址
Bitbucket 私有仓库不能像公开包那样直接用 vendor/package 名字拉取，必须显式声明 repository 类型为 vcs，并给出完整 HTTPS 地址（不是网页 URL）。常见错误是填成 https://bitbucket.org/username/repo —— 这会触发 404 或认证失败，正确地址末尾要带 .git。
-
type必须设为vcs，不能是package或留空 - URL 必须是 Git 协议兼容格式：
https://bitbucket.org/username/repo.git - 如果仓库启用了子模块或 LFS，需确认 Bitbucket 账户有对应权限，否则
composer install会在 clone 阶段卡住
{
"repositories": [
{
"type": "vcs",
"url": "https://bitbucket.org/your-org/internal-sdk.git"
}
],
"require": {
"your-org/internal-sdk": "^1.2"
}
}
Bitbucket 应用密码怎么配、怎么让 Composer 认得它
Bitbucket 不再支持账户密码直连 Git，必须用「应用密码（App Password）」替代。这个密码不是你在 Bitbucket 网页登录用的密码，而是在账号设置里单独生成的一次性密钥，且需勾选 Repositories: Read 权限（如果要 push 还要加 Write）。
- 生成后立刻复制保存——页面关闭就再也看不到明文了
- Composer 不会自动读取环境变量里的密码，必须通过
composer config命令存进本地auth.json - 不要把密码硬编码在
composer.json或提交到 Git，auth.json默认被.gitignore排除，但需确认项目根目录下确实存在且权限为600
composer config http-basic.bitbucket.org your-username your-app-password
执行后，Composer 会在项目根目录生成或更新 auth.json，内容类似：
{
"http-basic": {
"bitbucket.org": {
"username": "your-username",
"password": "APP_PASSWORD_HERE"
}
}
}
为什么 composer install 还是报 401 或 “Could not fetch”
最常踩的坑不是密码错，而是认证域没对上。Bitbucket 的 HTTP Basic 认证域是 bitbucket.org，不是 https://bitbucket.org，也不是你的仓库子域名（比如 your-org@bitbucket.org）。少一个点、多一个协议头，Composer 就找不到凭据。
- 检查
auth.json里http-basic下的 key 是不是纯bitbucket.org - 运行
composer config --global --list看全局配置有没有冲突的http-basic条目 - 用
composer diagnose可发现未加密的密码字段（Composer 8+ 会警告），此时需删掉auth.json重配 - 如果公司用了 Bitbucket Server（非 bitbucket.org），URL 和认证域都要换成你内网的域名，比如
bb.your-company.com
CI 环境（如 GitHub Actions / GitLab CI）怎么安全传密码
CI 里不能交互输密码，也不能把 auth.json 提交上去。正确做法是把应用密码存为 CI 的 secret，然后在 job 中动态生成 auth.json 文件。注意路径和权限：必须放在项目根目录，且不能被其他用户读取。
- GitHub Actions 示例中，
auth.json必须用echo写入，不能靠composer config命令（因为没交互终端） - 密码变量名要全大写、下划线分隔，例如
BITBUCKET_APP_PASSWORD，避免 shell 解析出错 - 生成后立即
chmod 600 auth.json，否则 Composer 8+ 会拒绝读取
echo '{"http-basic": {"bitbucket.org": {"username": "your-ci-user", "password": "'"$BITBUCKET_APP_PASSWORD"'"}}}' > auth.json
chmod 600 auth.json
Bitbucket 应用密码只绑定用户名和权限范围，不绑定 IP 或设备。一旦泄露，只能去 Bitbucket 后台手动删除，没法“禁用某一次使用”。所以每次 CI 配置完，最好立刻在 Bitbucket 的「个人设置 → 应用密码」列表里核对名称和创建时间。 
