因为公共镜像站（如阿里云、腾讯云）不开放同步接口，仅提供静态文件；真正可触发同步的是私有镜像服务的认证API端点，需POST请求、正确Header及JSON体。
为什么 curl 调用 Composer 镜像接口总返回 404 或空响应
因为官方镜像（如 packagist.org）不开放直接的 REST 同步接口，所谓“同步接口”实际是镜像站自建的内部服务，比如腾讯云、阿里云、华为云等镜像站提供的 /mirrors/sync 或 /api/v1/sync 端点——但这些接口**默认关闭认证、禁止公网调用、或仅限内网触发**。直接 curl https://mirrors.cloud.tencent.com/composer/mirrors/sync 必然失败。
实操前必须确认：你访问的是自己部署的私有镜像服务（如使用 packagist-mirror 或 composer-proxy），而非公共镜像站的前端域名。
- 公共镜像站（如
https://mirrors.aliyun.com/composer/）只提供静态包文件和packages.json，不响应同步请求 - 真正可手动触发同步的端点通常形如
http://localhost:8080/api/sync或http://your-mirror.internal/api/v1/trigger，需查你所用镜像服务的文档 - 多数服务要求 POST 请求 + JSON body + 认证头（如
X-API-Key），GET 直接访问基本无效
如何用 curl 正确触发私有镜像同步（含认证与参数）
以开源项目 packagist-mirror 为例，它默认启用 /api/v1/sync 端点，支持按 vendor 触发增量同步。关键不是“能不能 curl”，而是“带不带对的头和体”。
- 必须用
POST，不能用GET；Content-Type: application/json不可省略 - 若配置了
API_KEY（推荐），需加请求头：-H "X-API-Key: your-secret-key" - 想同步所有包，body 为空 JSON：
{}；想同步指定命名空间，传{"vendor": "monolog"} - 加上
-v查看完整请求/响应头，确认状态码是否为202 Accepted（异步任务）而非200 OK
示例命令：
CurlShip Directory Submission
下载
向CurlShip提交产品，这是一个对机器人友好的SaaS目录。只需一条curl命令即可发布产品，支持OG标签抓取、带徽章的dofollow链接及层级升级。
curl -X POST http://localhost:8080/api/v1/sync \
-H "X-API-Key: abc123" \
-H "Content-Type: application/json" \
-d '{"vendor": "symfony"}' \
-v
curl 返回 401 / 403 时该检查什么
这不是网络问题，是鉴权链路断在某个环节。常见原因比想象中更琐碎：
-
X-API-Key值错误、拼写多空格、大小写敏感（如配置是AbC123，但请求写了abc123） - 镜像服务配置里把
API_KEY设为""或注释掉了，导致认证逻辑被跳过，但接口仍校验头 - 反向代理（如 Nginx）过滤了带下划线的 header，默认丢弃
X-API-Key；需在 proxy 配置中显式放行：underscores_in_headers on; - 服务监听在
127.0.0.1而非0.0.0.0，curl localhost成功，但用宿主机 IP 就失败
同步没反应？别只盯着 curl 响应，先看服务日志
curl -v 显示 202 只代表任务已入队，不代表执行成功。镜像同步是耗时操作，可能卡在下载、解压、数据库写入任一环节。
- 立刻查镜像服务的标准输出或日志文件（如
pm2 logs、journalctl -u composer-mirror、或项目里的storage/logs/laravel.log） - 搜索关键词：
sync started、fetch failed、SQLSTATE[HY000]（MySQL 连接失败）、file_put_contents（磁盘满或权限不足） - 注意时间戳——如果日志里根本没有对应时间的 sync 记录，说明请求根本没进到应用层，问题出在反向代理或防火墙
同步逻辑复杂，依赖网络、磁盘、数据库、PHP 扩展（如 zip、openssl）全部就绪。一个 curl 命令只是扳机，后面全是黑盒。
