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 会导致整个依赖树重算，风险极高。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

优先用 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 会基于空目录生成，上线就炸。