Composer镜像配置必须严格满足三要素：键名repo.packagist、type值为composer、URL以/结尾；缺一不可，否则静默失效；项目级需置入repositories数组首位并禁用packagist.org，且须删vendor和composer.lock后重装。
镜像配置和包发布是两件事，不能混为一谈——配镜像只是加速下载，不影响包能否被别人 require；而发布失败、本地类找不到、CI 报错 Class not found，90% 是因为 composer.json 没写对，不是网络慢。
composer config -g repo.packagist 命令必须带全三要素
全局换源最快的方式就是这条命令，但漏掉任意一个，配置就白写，且不报错：
-
repo.packagist是唯一有效的键名——写成repos.packagist（多一个 s）或mirror都无效 - 必须显式指定
composer作为 type 值，不能省略；省略后 Composer 2.x+ 会 fallback 到默认源 - 镜像 URL 必须以
/结尾，例如https://mirrors.aliyun.com/composer/✅，少斜杠会导致请求路径拼错，返回 404
验证是否生效：运行 composer config -g repo.packagist，输出应为完整 JSON 对象，不是空或 null。
项目级镜像必须写进 composer.json 的 repositories 数组首位
项目级镜像只对当前项目起作用，但生效条件非常严格：
立即学习“PHP免费学习笔记（深入）”；
- 必须作为
"type": "composer"的仓库对象，放入repositories数组的**第一个位置** - 必须显式禁用官方源：
{"packagist.org": false}是独立对象，不是字段值，也不能合并到前一个对象里 - 错误示例（会被忽略）：
"repositories": {"packagist": {"type": "composer", "url": ""}}—— 这是对象写法，不是数组，且没禁用packagist.org
改完配置后必须删 vendor 和 composer.lock 再执行 composer install。Composer 不会“重新解析”已存在的 composer.lock——它照着 lock 文件里的 dist URL 直接下载，根本不管 repositories 配了啥。
SDK 包的 composer.json 必须由 composer init 生成，别手写
90% 的包发布失败或本地加载异常，根源是 JSON 格式错误：全角引号、BOM 头、末尾逗号、路径拼写错误。这些错误 composer install 不报具体位置，只抛 JSON decode error。
- 执行
composer init，按提示填name（格式必须是vendor/name）、type（库选library）、autoload（推荐 PSR-4） - 它会自动探测
src/目录并建议命名空间，比你手动写"App": "src/"更可靠 - 生成后立刻运行
composer validate，它能秒级发现字段缺失、版本约束语法错误、命名空间未结尾等硬伤
PSR-4 autoload 的三个死线
Composer 不在运行时读 composer.json，而是在 dump-autoload 时把规则编译进 vendor/autoload.php。配错不会警告，只会让类永远找不到：
-
namespace必须以反斜杠结尾："MyPackage\": "src/"✅，"MyPackage": "src/"❌ -
path必须以正斜杠结尾，且相对composer.json所在目录："src/"✅，"./src"❌，"src"❌ - 改完
autoload后必须手动执行composer dump-autoload（加-o生成优化版，生产环境用）
最常被忽略的是：发布前必须打 Git tag，且格式为 v1.0.0。Packagist 不读 GitHub 的分支名，只认符合 SemVer 的 tag。没 tag = 没版本 = 别人 require 时只能写 "dev-main"，等于放弃语义化版本控制。
