Bitbucket私有包拉不下来主因是认证或仓库配置错误：必须执行composer config --global bitbucket-oauth.bitbucket.org配置App Password，且composer.json中repositories需满足type为"vcs"、url以.git结尾、包名与私有库name字段逐字一致。
Bitbucket 私有包拉不下来？不是缓存问题，是认证或仓库配置没对——Composer 的 VCS 类型根本不用“配缓存”，它压根不走 Packagist 那套元数据缓存逻辑。
为什么 composer clear-cache 对 Bitbucket VCS 无效
Composer 的缓存分两层：HTTP 层（packages.json、ZIP 包）和 Git 层（克隆后的仓库副本）。VCS 类型（"type": "vcs"）跳过所有 HTTP 元数据缓存，每次 install/update 都直接解析远程 Git 仓库的 composer.json，并执行 git clone 或 git fetch。所以：
– composer clear-cache 只清 HTTP 缓存，不影响 Git 克隆行为
– vendor/ 下已克隆的仓库会被复用（Git 层缓存），但这是 Git 自己的行为，不是 Composer 控制的
– 你看到“卡住”“403”“Could not fetch”，99% 是认证失败或 URL 不合法，跟缓存无关
composer.json 中 VCS 仓库声明必须满足的三个硬条件
即使 auth.json 配对了，只要漏掉任意一条，Composer 就当公开包处理，完全不触发 Bitbucket 认证：
-
"type": "vcs"必须显式写出，不能是"git"、"package"或留空 -
"url"必须是完整 HTTPS 克隆地址，且以.git结尾，例如"https://bitbucket.org/myorg/private-lib.git"；填网页地址、少.git、加/src路径都会导致 404 - require 中的包名（如
"myorg/private-lib"）必须和私有仓库根目录下composer.json的"name"字段**逐字节一致**（含大小写、斜杠方向）
bitbucket-oauth.bitbucket.org 是唯一入口，别碰 auth.json 手动写
Composer 2+ 彻底废弃 http-basic.bitbucket.org 和 OAuth consumer，只认 bitbucket-oauth.bitbucket.org 这一个配置项。它内部会自动：
- 校验域名是否严格等于
bitbucket.org（不接受www.、api.、带https://前缀） - 把值当成 App Password 处理（必须是你个人账号生成，权限至少勾选
Repositories: Read） - 安全写入
auth.json并设权限为600（手写容易权限错、字段错位、JSON 格式错，结果静默跳过认证）
正确命令只有一条：composer config --global bitbucket-oauth.bitbucket.org your_app_password_here
Git 层卡在 Cloning into 怎么排查
这不是 Composer 配置问题，是系统 git 命令本身失败。必须手动复现：
- 运行
git clone https://bitbucket.org/myorg/private-lib.git /tmp/test-clone，看是否同样卡住 - 若卡在 HTTPS，确认 App Password 没复制漏字符、没过期、权限勾对；也检查是否被公司代理拦截（需设
git config --global http.proxy） - 若用 SSH（
git@bitbucket.org:...），则ssh -T git@bitbucket.org必须通，否则换 HTTPS + App Password - SSL 报错（
SSL certificate problem）说明 Git 没读系统证书路径，执行git config --global http.sslCAInfo "/etc/ssl/certs/ca-certificates.crt"（Linux）或对应 Windows 路径
真正需要调的从来不是“缓存设置”，而是让 git clone 在终端里能跑通——Composer 只是调用了它。
