答案是composer.json必须从第一行写{，使用utf-8无bom编码，禁用中文引号、tab缩进、尾随逗号；键名和字符串须用英文双引号，require末项后不加逗号，psr-4命名空间末尾用双反斜杠、路径末尾用正斜杠，name字段须为小写vendor/name格式。

composer.json 必须从第一行写 {，且用 UTF-8 无 BOM 编码

很多 composer install 报错 JSON decode error: Syntax error，根本原因不是语法写错，而是文件开头藏了不可见的 BOM 字节，或用了中文引号、Tab 缩进、尾随逗号。

实操建议：

Pandas 配置文件报告生成器

使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。

下载

• 用 VS Code、Sublime 或 Vim 新建纯文本文件，编码选「UTF-8 without BOM」
• 第一行必须是 {，前面不能有任何空格、空行、注释或隐藏字符
• 所有字符串（包括键名）必须用英文双引号 "，比如 "name"，不能写 name
• require 末项后不能加逗号，"php": "^8.1" 后面直接跟 } 或换行
• 写完立刻去 jsonlint.com 粘贴校验，别靠肉眼数括号

name 字段必须是 vendor/name 格式，小写+短横线+斜杠

填错 name 不会立刻报错，但后续 composer install 可能静默失败，或者 Packagist 拒绝提交，CI 流程卡在依赖解析阶段。

实操建议：

• 格式强制为两段：前段是 vendor（如 GitHub 用户名 myorg），后段是包名（如 my-awesome-tool），中间用 / 连接 → "name": "myorg/my-awesome-tool"
• 不允许大写字母、下划线、空格、点号、中文；MyApp、my_app、my app 全部非法
• 本地私有项目可暂用 "name": "local/test-app"，但上线前必须改真实标识
• 不填 name 会导致 composer init 直接退出，并报 The package name is invalid.

autoload 的 psr-4 映射路径必须以 / 结尾，且命名空间末尾带反斜杠

类加载失败（Class not found）十次里有七次是这里写错了。Composer 不会提示“你少了个斜杠”，只会默默去找错路径。

实操建议：

• 正确写法："App\": "src/" —— 命名空间末尾是双反斜杠（JSON 转义），路径末尾是正斜杠
• 错误写法："App": "src"（路径没斜杠 → 找 srcFoo.php）、"App": "src/"（少反斜杠 → 不识别为命名空间前缀）
• 目录 src/ 必须真实存在，且相对于 composer.json 所在路径
• 改完必须运行 composer dump-autoload -o，否则缓存不变，new AppFoo() 依然报错
• 如果项目含全局函数文件（如 functions.php），加到 autoload.files 数组里，别硬塞进 psr-4

require 和 require-dev 放错位置，上线就出问题

开发时一切正常，composer install --no-dev 部署后却 Class not found 或 HTTP 请求发不出——大概率是依赖放错了栏位。

实操建议：

• require：运行时真要 new、use、include 的包，比如 "monolog/monolog"、"guzzlehttp/guzzle"
• require-dev：只在 tests/、bin/、CI 脚本里出现的工具，比如 "phpunit/phpunit"、"phpstan/phpstan"
• 框架核心包（如 "laravel/framework"）永远进 require，哪怕你只在本地跑 artisan
• 执行 composer install --no-dev 后，用 composer show 确认线上环境没多装任何 require-dev 包
• CI 中务必加 --prefer-dist，避免因本地 vendor/ 状态污染导致版本解析异常

最常被忽略的一点：修改 repositories 配置后，不删 composer.lock 就跑 composer install，它仍会按 lock 文件里旧的 dist.url 去请求，新镜像配置完全不生效。