composer.json必须用utf-8无bom编码、英文双引号、首行{、无尾逗号；镜像配置须手动编辑repositories并禁用packagist.org，全局配置仅认composer config -g repo.packagist，且必须执行clear-cache。
composer.json 文件必须从第一行写 {，别加 BOM、别用中文引号
手动写 composer.json 最常卡在“文件根本读不了”——不是逻辑错，是编码或符号错了。Composer 只认 UTF-8 无 BOM 的纯文本，且对 JSON 格式零容忍。
- 新建文件时，在 VS Code / Sublime / Vim 中选“UTF-8 without BOM”，不要用记事本、Word 或 Excel 保存
- 所有键名和字符串必须用英文双引号
"name"，不能是中文引号“name”，也不能不加引号name - 第一行必须是
{，前面不能有空行、空格或隐藏字符（比如复制网页内容带的不可见 Unicode） - 对象末尾不能有逗号：
"require": { "php": "^8.1" }里"php": "^8.1"后面不能加逗号 - 写完立刻去 jsonlint.com 粘贴校验，报错就停手，别硬试
composer install
项目级镜像配置别用 composer config repo.packagist，会清空原有 repositories
这条命令看似方便，实则危险：它不是追加，而是全量替换 composer.json 中的 repositories 字段。如果你项目原本就配了私有 Git 包源，执行后直接消失，composer install 会报 Could not find package xxx。
- 正确做法是手动编辑
composer.json，把镜像作为数组第一项插入repositories - 必须显式禁用官方源：
{"packagist.org": false}要放在repositories数组最前面 - 阿里云镜像 URL 必须带结尾斜杠：
"url": "https://mirrors.aliyun.com/composer/"，少一个/就静默 fallback 到官方源 - 示例结构（注意顺序和格式）：
{
"repositories": [
{"packagist.org": false},
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
],
"require": {
"php": "^8.1"
}
}
全局镜像配置只认 composer config -g repo.packagist，漏 -g 就写进当前项目
想一劳永逸？那就只信这一条命令。其他写法——比如手改 ~/.composer/config.json、用旧键名 repos.packagist、漏掉中间的 composer 类型参数——都会导致配置静默失效。
- 必须带
-g：不加就是项目级，会污染composer.json - 必须写全三段：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - Windows 用户改完要重启终端，否则环境没刷新，
composer config -g repo.packagist查不到新值 - 验证是否生效：运行
composer config -g repo.packagist，输出必须是完整 JSON，含"type": "composer"和以/结尾的url - 改完立刻执行
composer clear-cache，否则旧缓存会让composer update还走官方源
name 和 type 字段不是“可填可不填”的装饰项
这两个字段看着可选，但填错或漏填会在特定场景下引发真实问题，尤其当你后续要发布包、集成框架安装器、或迁移到 CI 环境时。
-
name：私有项目可省略，但建议填，格式为"vendor/name"（如"myorg/myapp"）；不填会导致composer show显示为空，部分自动化工具无法识别项目身份 -
type：默认是"library"，但如果你是 Laravel 应用，填"project"；是 WordPress 插件，填"wordpress-plugin"；是 Symfony Bundle，填"symfony-bundle" - 填对
type才能触发对应安装器逻辑，比如自动把插件放进wp-content/plugins/，而不是全扔进vendor/里让你手动挪 - 不确定类型时先不填，等真要用到安装器机制再补，别为了“格式整齐”乱填——填错比不填更麻烦
composer config -g 输出看着正常，只要没跑 composer clear-cache 或 URL 少了个 /，composer install 就还在连 packagist.org。
