composer.json 的 name 字段必须严格为全小写、vendor/name 格式（如"acme/blog-api"），不可省略vendor、不可含大写字母或下划线，否则导致autoload失败、依赖解析异常等静默错误。
Composer 不是“装完就能用”的工具，它对项目结构、PHP 环境、配置格式和操作流程都有隐性但刚性的要求。填错一个 name 字段、漏掉一个反斜杠、手动改一行 composer.lock，都可能让 Class not found 报错在生产环境凌晨三点出现，且毫无上下文。
composer.json 的 name 字段必须严格为 vendor/name 格式
这个字段不是可选的“项目名”，而是 Composer 依赖解析和自动加载的根标识。不填、格式错、大小写混用，都会导致静默失败——composer install 不报错，但后续所有 autoload、require 本地路径包、甚至 composer dump-autoload 都可能失效。
-
name必须是全小写、两个单词、单斜杠分隔，例如"acme/blog-api"；不能是"AcmeBlogApi"、"blog-api"或"my-project" - vendor 名建议与 GitHub 组织名一致（方便 Packagist 同步），哪怕只是本地脚本，也应填占位值如
"local/scripts"，绝不可为空或仅写"scripts" - 如果项目 require 了本地路径包（
"path": "../some-lib"），name格式错误会导致路径解析失败，报错却指向“找不到包”，而非“name 不合法”
PSR-4 路径末尾必须带斜杠，且目录必须真实存在
PSR-4 映射不是字符串拼接，而是命名空间前缀到物理路径的精确映射。Composer 不校验路径是否存在，也不补全斜杠，运行时才暴露问题。
- 错误写法：
"App": "src/App"→ 会尝试加载src/AppSomeClass.php（缺目录分隔） - 正确写法：
"App\": "src/App/"（JSON 中双反斜杠表示单反斜杠，末尾斜杠不可省） - 路径是相对于
composer.json所在目录的相对路径，不要加./，也不要写绝对路径 - 改完
autoload后，必须手动执行composer dump-autoload，install或update不会自动触发
别手动编辑 composer.lock，用 composer update --lock 替代
composer.lock 是依赖快照，不是配置文件。它包含 content-hash、子依赖树、文件哈希等几十个强耦合字段，手动修改等于破坏校验链。
- 常见现象：改完 lock 文件后
composer install报Invalid argument supplied for foreach()（实际是 JSON 解析失败） - 更危险的是：你只改了一个包版本，但没同步更新它的子依赖列表和哈希值，导致本地能跑、CI 构建失败、别人装出不同 vendor
- 安全做法只有两种：
composer update --lock（重算 lock，不碰 vendor）或删 lock 后composer install（放弃锁定，重新求解整个依赖树） - 适用
update --lock的典型场景：改了composer.json里的require或require-dev，但不想重装 vendor；团队误删 lock，你有干净 vendor 想快速恢复
镜像源配置失败？先查权限、再查项目级覆盖
国内换阿里云镜像常卡在“配置了却不生效”，根本原因往往不是网络，而是权限或配置层级冲突。
- Linux/macOS 下执行
composer config -g repo.packagist ...报Permission denied，是因为当前用户无权写入全局配置目录；应先运行composer config -g home获取路径，再用sudo chown -R $USER:$USER [path]修复权限 - 即使全局配了镜像，项目级
composer.json中若含"repositories": { "packagist": { "url": "https://packagist.org" } }，就会直接覆盖全局设置 - Docker 环境中，建议在构建阶段就配置镜像，避免运行时因权限或网络策略失败；临时调试可用
COMPOSER_MIRROR=https://mirrors.aliyun.com/composer/ composer install
最易被忽略的一点：Composer 的行为高度依赖 PHP 运行时环境是否一致。开发机装了 sodium 扩展，而生产机没装，composer install 成功，但运行时报 Class 'Sodium...' not found —— 这类问题不会出现在 lock 文件里，也不会被 composer validate 捕获，只能靠部署前检查 php -m 和 composer show --platform。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
