Craft CMS 官方推荐使用 ^（caret），如 "^5.0.0"，因其允许 5.x.y 升级但禁止升至 6.0.0，契合其主版本即破坏性变更的语义化版本策略。
composer.json 里该用 ^ 还是 ~？Craft CMS 官方推荐怎么写
Craft CMS 官方在 composer.json 示例中统一使用 ^（caret）约束，比如 "craftcms/cms": "^5.0.0"。这不是随意选的——^5.0.0 允许安装 5.x.y 所有版本，但禁止升到 6.0.0，正好匹配 Craft 的语义化版本策略：主版本升级 = 破坏性变更。
别用 ~5.0（波浪号），它等价于 >=5.0.0 ，会卡死在 <code>5.0.x，错过 5.1 里的安全补丁和非破坏性功能更新。
- 插件依赖也照此原则：若插件声明支持
"craftcms/cms": "^5.0"，你就别手动改成"5.0.0"或"5.*" - PHP 版本约束必须显式写进
config.platform.php，例如"platform": {"php": "8.2.0"}，否则 Docker 构建时可能因宿主机 PHP 版本误判而装错扩展 - 避免混用约束符号：同一项目里不要有的包用
^、有的用~或*，这会让composer update行为不可预测
为什么 craftcms/docker 镜像里 composer install 比 update 更关键
官方镜像（craftcms/docker）默认执行的是 composer install --no-dev --optimize-autoloader，不是 update。因为容器启动是“部署行为”，不是“开发行为”——它必须复现 composer.lock 记录的精确依赖树，而非重新解析。
常见错误是把本地开发流程直接套进 CI/CD：在 GitLab CI 里跑 composer update 再生成新 lock，结果镜像里装的包和本地不一致。正确做法是：
-
composer.lock必须提交进 Git，且不能被.gitignore排除 - CI 流水线第一步加
ls -la composer.lock检查文件是否存在、是否为空 - Dockerfile 中明确用
RUN composer install --no-dev --optimize-autoloader，禁用--ignore-platform-reqs - 如果要升级依赖，先在本地运行
composer update craftcms/cms（只升核心），确认无 break 后再提交新lock
插件版本冲突时，别删 lock 文件，先跑这两条命令
当你执行 composer require supercool/super-table 报错 Your requirements could not be resolved，大概率是已有插件锁定了某个包的旧版。盲目删 composer.lock 会导致整个依赖树重算，风险极高。
优先用 Composer 自带诊断工具定位根因：
-
composer prohibits supercool/super-table：列出所有阻止该插件安装的包及其约束条件，比如输出your/project v1.0.0 requires craftcms/cms 5.0.0，说明是项目自身卡死了 CMS 版本 -
composer why-not craftcms/cms:5.1.0：检查为何不能升到指定版本，常会暴露某个插件只兼容5.0.* - 再配合
composer diagnose确认 PHP 版本、扩展（如ext-intl）是否满足目标插件要求
真正要动 lock 文件，只应在验证完 prohibits 输出后，针对性修改 composer.json 中冲突项的约束，再跑 composer update --lock。
autoload 性能陷阱：Craft 项目里 classmap 和 PSR-4 怎么配才不拖慢请求
Craft 默认的 "autoload": {"psr-4": {"craft\": "src/"}} 在大型插件或自定义模块里容易变慢——因为 PSR-4 会扫描整个 src/ 目录树找类文件，而 src/ 下常混着 config/、migrations/、templates/ 等非类目录。
优化方式不是简单加 --optimize-autoloader，而是重构 autoload 结构：
- 把真正放类的路径单独拆出来：
"App\": "src/app/"、"Plugin\": "src/plugin/" - 对单文件类（如
src/helpers/ArrayHelper.php）用"classmap": ["src/helpers/"]显式注册 - 生产环境构建镜像时，固定加
composer dump-autoload --classmap-authoritative -o，让 autoloader 完全跳过文件系统扫描 - 注意：
--classmap-authoritative要求所有类都在 classmap 里，否则报Class not found，所以必须确保src/下没有漏掉的类文件
最易被忽略的是：Docker 构建阶段的 composer dump-autoload 命令，必须放在 COPY . . 之后、composer install 之前，否则 classmap 会基于空目录生成，上线就炸。
