Packagist不提供写入API，“双向同步”是伪命题；所有同步均为单向：企业侧通过Git webhook或CI主动推送，镜像侧被动拉取，且私有包无法进入Packagist。
“双向同步”本质是伪命题，Packagist不提供写入接口
Composer 官方 Packagist.org 是只读元数据索引服务，没有 API 接收私有包注册或更新请求。所谓“双向同步”，实际是企业侧单向推送 + 镜像侧单向拉取，两者协议、权限、触发机制完全隔离。强行套用“双向”概念，容易误判架构责任边界。
典型错误认知：packagist.org 能接收你内网 Satis 或 Artifactory 的 POST /api/update 请求——它根本不存在这个端点。所有“同步”动作必须由你控制的构建节点主动发起，且只能走 HTTPS Git 拉取或 HTTP PUT 推送两类路径。
- 对外镜像（如阿里云）：只能被动拉取
packages.json和provider-*.json，延迟几小时属正常，无法强制刷新 - 对内私有源（如 Artifactory）：必须由 CI 流水线通过
curl -X PUT或composer publish主动推送新版本元数据，不能依赖定时轮询 - Git Tag 是唯一可信信号源：
v1.2.3标签推送到 GitHub/GitLab 后，才应触发内网构建；镜像站无权决定哪些 tag 该同步
混合云下元数据一致性靠“时间戳+版本戳”双校验
公有云镜像（如 https://mirrors.aliyun.com/composer/）和私有云 Satis/Artifactory 不可能实时一致。硬要“强一致”，只会导致超时、重试风暴或客户端解析失败。真正可行的是用可验证的时间锚点替代“同步完成”假定。
实操要点：
- 在 Satis 构建脚本末尾生成
build-timestamp.json，内容为{"ts": "2026-07-16T12:34:56Z", "commit": "abc123"}，并随packages.json一同发布 - Artifactory 用户启用
repo.replication时，务必开启syncProperties，确保自定义属性（如build.ts）随 artifact 一起复制 - 客户端可通过
curl -s https://pkgs.internal/build-timestamp.json | jq .ts对比本地缓存时间，决定是否composer clear-cache - 禁止用
mtime或 NginxLast-Modified做判断——Satis 静态文件的修改时间与实际构建时间无关
私有包进公有镜像？别试了，官方不接受
想把 acme/internal-sdk 提交到 packagist.org 让外部用户安装？这条路已被彻底堵死。Packagist 明确拒绝非公开仓库、无合法 composer.json 或缺失 name 字段的提交，且不提供企业白名单机制。
常见失败现象：
- 提交 URL 后页面显示 “Package not valid”，但不提示具体哪条校验失败
-
composer require acme/internal-sdk在本地能跑通（因用了type: vcs），但一上传 CI 就报Could not find package - 误以为改
composer.json里的repositories就能让 Packagist “看到”你的包——它根本不读你的项目配置
替代方案只有两个：要么让下游项目显式声明 "type": "vcs" 指向你的 Git 地址；要么用 Artifactory 开启 composer virtual repository，把私有源和 public packagist.org 聚合成一个统一入口，但对外仍不可见。
Nginx 缓存配置是混合云链路中最容易被忽略的断点
哪怕 Satis/Artifactory 构建正确、Git Tag 推送及时、CI 推送成功，只要 Nginx 缓存策略写错，客户端就永远拿不到最新元数据。这不是 Composer 问题，而是 HTTP 层的隐性故障。
关键配置项（Nginx）：
-
proxy_cache_valid 200 302 300s;——packages.json和provider-*.json必须设短 TTL（建议 ≤300s），否则 CDN 缓存过期前，新 tag 永远不生效 -
proxy_cache_bypass $arg_no_cache;+proxy_no_cache $arg_no_cache;—— 运维调试时加?no_cache=1可绕过缓存，避免反复清 CDN -
add_header X-Cache-Status $upstream_cache_status;—— 必须加，否则无法快速区分是源站未更新，还是缓存没刷新 - 绝对不要用
expires max;或Cache-Control: public, max-age=31536000—— 元数据不是静态资源，缓存一年等于锁死版本
最常被漏掉的一点：proxy_cache_key 必须包含 $scheme$host$request_uri，否则 HTTPS 和 HTTP 请求会共用同一缓存块，导致协议切换后返回错误内容。
