私有包发布前，composer.json 必须满足 name、type、autoload 三个硬性字段：name 必须为小写 vendor/package-name 格式且与仓库路径和 require 引用名完全一致；type 建议显式设为 library；autoload 至少含一个有效 psr-4 映射，否则自动加载失败或 satis 静默忽略。
私有包发布前，composer.json 必须满足哪几个硬性字段
不满足就进不了仓库、装不上、CI 直接报错。Packagist 或 Satis 都会校验，但私有源（如 GitLab + Satis）更宽松些——可一旦漏掉关键字段，下游项目 composer require 就会卡在 “Could not find package”。
-
name必须是小写vendor/package-name格式，且和 Git 仓库路径、require 引用名完全一致；Acme/utils和acme/utils是两个包 -
type显式设为library（非必需但强烈建议），否则某些私有源索引逻辑可能跳过该包 -
autoload至少含一个有效 PSR-4 映射，空对象{}或缺失会导致自动加载失败，且 Satis 构建时可能静默忽略 -
description不强制，但缺失时 Satis 页面显示为空白，团队内部难以识别用途
GitLab 私有仓库 + Satis 自动构建，怎么配才不掉链子
常见问题是 Satis 构建成功但下游 composer install 找不到包，根源往往不在 Satis 本身，而在 GitLab 访问权限或 URL 匹配规则。
-
repositories必须写在主项目composer.json顶层，且每项url必须带.git后缀：例如"https://gitlab.example.com/acme/utils.git"，缺了就报No valid composer.json was found - Satis 的
satis.json中repositories列表里的url必须和 GitLab 仓库实际 clone 地址完全一致（协议、域名、路径、.git），否则构建时拉不到代码 - GitLab Token 必须放在
~/.composer/auth.json，字段是http-basic，key 是纯域名（如gitlab.example.com），不能带端口或路径；权限必须chmod 600，否则 Composer 静默跳过认证 - Satis 构建命令应加
-v参数跑一次，看日志里是否真实 clone 成功——很多失败其实卡在 SSH key 或 Token 权限，不是配置问题
谁有权限打 tag？tag 命名和推送为什么必须人工确认
私有包的 tag 不是“发版”，而是生产环境依赖锚点。打错一个 tag，所有 require "acme/utils": "^2.1" 的项目都会锁定到错误版本，回滚成本极高。
- 只有 Tech Lead 或 Infra 组成员可执行
git tag v2.1.0 -m "release: security fix"，且必须基于已通过 CI 全量测试的 commit - tag 名必须严格语义化：
v2.1.0✅，2.1.0❌，V2.1.0❌，release/2.1.0❌；Satis 和 Composer 都只认v开头的标准格式 - 必须
git push origin v2.1.0（不是git push --tags），后者容易漏推、或把开发分支的临时 tag 也推上去 - 打完 tag 后，立刻在 Satis 服务器手动触发
php satis build satis.json public/，并检查生成的packages.json是否包含新版本条目——别等下游报错了才查
CI 流水线里如何安全触发私有包发布
自动化发布不是“一推就发”，而是“一推+人工审批+验证+构建”四步闭环。跳过任何一步，都可能把未测代码打进生产依赖。
- GitHub Actions / GitLab CI 应监听
push事件，但仅对tags触发，且正则匹配^v[0-9]+\.[0-9]+\.[0-9]+(-[a-z0-9]+)?$ - 流水线第一步必须运行
composer validate --strict，校验composer.json合法性；第二步跑全部单元+集成测试；任一失败立即终止 - 构建阶段不能直接改生产 Satis 服务，而是生成临时静态包目录，用
rsync或scp推送到 Satis 服务器后，再执行php satis build - 最后一步必须 curl 检查新包是否可被
composer show acme/utils v2.1.0正确解析，否则发告警而不是静默失败
composer.json 里的 name 和 GitLab 仓库 URL、下游项目 require 字符串、Satis 配置中的 url ——这四处必须字节级一致。差一个斜杠、大小写、或 .git 后缀，整个链路就断在“找不到包”，而错误提示不会告诉你哪一处错了。
