composer.json 的 name 字段必须为 "vendor/name" 格式，vendor 不能纯数字或下划线开头；psr-4 映射需写成 "namespace\": "src/"，路径相对 composer.json；php 版本约束应设为 "php": "^8.1"；scripts 优先用 post-autoload-dump 并加 --no-interaction。
composer.json 里 name 字段必须带 vendor 名称
不填 vendor 会导致 Packagist 拒绝发布，本地 require 也会报 Package name must be lowercase and contain only letters, digits, underscores, hyphens and dots。很多新手直接写 "name": "myapp"，结果后续所有命令都失败。
- 正确格式是
"name": "vendor/myapp"，vendor 通常是公司名、GitHub 用户名或组织名，不能是纯数字或下划线开头 - 如果只是本地开发不发包，也建议照写——否则将来迁移时要改一堆地方，包括 autoload、PSR-4 命名空间、CI 脚本
- vendor 名和 GitHub 用户名不强制一致，但强烈建议统一，避免团队成员 clone 后手动改
name再 commit
autoload 配置错一行，类就找不到
PSR-4 映射路径写错最常见：不是“源码路径”，而是“命名空间前缀 → 目录相对路径”的映射关系。比如项目根目录下有 src/Http/Client.php，对应命名空间 MyAppHttp，那配置就得是：
"autoload": {
"psr-4": {
"MyApp\": "src/"
}
}
-
"MyApp\"结尾双反斜杠是必须的，PHP 里转义用；单写"MyApp"会解析失败 -
"src/"是相对于composer.json所在目录的路径，不能写成./src/或src（少斜杠） - 改完记得运行
composer dump-autoload，否则新映射不生效；开发中可加-o生成优化加载文件
require-dev 里放 phpunit 就够了？别漏掉 php 版本约束
只写 "phpunit/phpunit": "^10" 不够，composer install 可能拉到不兼容的 PHP 运行时。Composer 会检查 require 和 require-dev 下所有包的 PHP 兼容性，但前提是你的 composer.json 显式声明了目标版本。
- 必须在
require或config里加"php": "^8.1"，推荐放在require（因为运行时依赖 PHP 解释器本身） - 不要用
"php": ">=8.1"—— Composer 不识别这种模糊写法，会当成字符串跳过校验 - CI 环境里如果没设
platform，可能因本地 PHP 版本高而装了高版本包，推到服务器就报Class not found
scripts 里写 "post-install-cmd" 很危险
这个钩子会在每次 composer install 后执行，包括 CI 构建、Docker 构建、甚至队友本地安装——一旦脚本出错，整个流程中断，且错误提示常被淹没在大量输出里。
- 优先用
"post-autoload-dump"，它只在 autoloader 更新时触发，更可控 - 所有 scripts 命令必须加
--no-interaction和--quiet，否则 CI 会卡住等待输入 - 如果脚本要生成文件（如 env 示例），务必判断文件是否存在再写，否则
composer update会反复覆盖用户已修改的配置
标准化模版最难的不是字段填全，而是每个键值背后都有运行时语义。少一个反斜杠、多一个点、路径差一级，项目就可能在某台机器上静默失败。写完记得用 composer validate 过一遍，它比人眼快得多。
