Gitee 不提供 Composer 镜像源，因其不支持 packages.json 接口与全量同步；正确做法是元数据用阿里云等国内镜像（如 https://mirrors.aliyun.com/composer/），私有包通过 vcs 类型仓库配置 Gitee 地址并完成认证。
不能用 Gitee 当 Composer 镜像源，它不提供 packages.json 接口，所谓“Gitee 镜像”基本都已失效或从未正式运行过；真正能配合使用的，是「Gitee 托管私有包 + 国内公共镜像加速元数据」这一组合。
为什么 composer config -g repo.packagist composer https://gitee.com/xxx 一定失败
这条命令看似在换源，实则违反 Packagist 协议：Gitee 不托管全量包索引、不生成 packages.json、也不支持按包名路由分发 ZIP 包。你执行后 composer config -g repo.packagist 可能返回空或 fallback 到官方源，但不会报错——静默失效才是最危险的。
-
https://gitee.com/composer/mirror等链接已返回 404 或空响应 - Gitee 官方自 2025 年底起明确声明未提供 Composer 公共镜像服务
- 即使 URL 能访问，也缺少
provider-includes、providers-url等关键字段，Composer 会直接跳过该源
正确配合方式：私有包走 Gitee VCS，元数据走阿里云/腾讯云镜像
你要的是「开发时能拉自己写的私有组件，安装时又快」，这需要两层配置并存，且互不干扰。
- 全局或项目级配置国内镜像（如
https://mirrors.aliyun.com/composer/），只负责加速packages.json下载和包发现 - 在项目
composer.json的repositories数组里单独加一条vcs类型源，指向你的 Gitee 仓库地址："type": "vcs", "url": "https://gitee.com/your-org/your-package.git" - 认证必须到位：HTTPS 方式需在
~/.composer/auth.json写入个人访问令牌（username填 token，password留空）；SSH 方式需密钥已添加到 Gitee 账户 - 包名必须完全一致：
"require": {"your-org/your-package": "^1.0"}中的命名要和 Gitee 仓库路径大小写严格匹配
composer install 还慢？先分清是哪一层卡住
镜像只影响元数据加载（Loading composer repositories 阶段），不影响 ZIP 包下载本身。如果你看到卡在 Downloading ...，那和镜像无关，而是直连 GitHub/GitLab 的问题。
立即学习“PHP免费学习笔记（深入）”；
- 卡在
Loading composer repositories→ 换镜像 +composer clear-cache能解决 - 卡在
Resolving dependencies→ 和镜像完全无关，检查composer.json中 PHP 版本约束是否太宽、dev 分支引用是否过多 - 卡在
Downloading ...→ 实际是下载 dist ZIP 包，Gitee 不代理这个环节；可临时改dist.url指向你 fork 后的 Gitee 地址，但需手动同步 tag，维护成本高 - 报
file could not be downloaded: failed to open stream→ 先确认allow_url_fopen开启，再curl -I https://mirrors.aliyun.com/composer/packages.json测试镜像可达性
最容易被忽略的点：换镜像后不执行 composer clear-cache，缓存里还是旧的元数据，Composer 会反复尝试从旧地址拉取校验信息，导致看似“换了源却没效果”。
