Craft CMS Operations 是面向 Craft CMS 代理机构站点构建的操作流程与路由文档，版本事实截至 2026-10-05 依据 Packagist 与官方文档核验：Craft 5.x 为当前版本（5.11），Craft 4 与 3 已过安全支持期，Craft 6 处于 alpha。脚本 scripts/check-craft-facts.py --live 可按计划重新核验插件主版本。
典型代理机构形态：Craft 5（或等待升级的 4/3 站点）运行在 DDEV 上，搭配 SEOmatic、Blitz、Formie、CKEditor，前端使用 Vite（或旧版 Laravel Mix），模块用 Codeception 与 ECS 测试。该文档是流程与路由器，每个主题各有独立参考文件。
第一步：动手前先定位。检查 Craft 与插件版本（composer.json、ddev composer show craftcms/cms）以确定适用的版本矩阵——Craft 4 与 5 的 API 不同；查看本地环境 .ddev/config.yaml 获取 PHP/DB 版本，所有操作以 ddev craft、ddev composer、ddev npm 运行；以 config/project/*.yaml 为 section、字段、条目类型、插件设置的唯一事实来源；查看 config/general.php、config/<plugin>.php、.env 了解环境相关行为（devMode、allowAdminChanges、缓存）；前端构建看 package.json 加 config/vite.php 或 webpack.mix.js，区分 craft-vite 与 Laravel Mix；模板看 templates/_layouts、_partials、_partials/entry/<type>.twig 的布局继承与元素分部；PHP 逻辑与测试位于 modules/、tests/、codeception.yml、ecs.php；页面缓存看 config/blitz.php 与 Blitz 工具，调试“改动不显示”前先确认看到的是否是缓存 HTML。
第二步：路由任务。列表页、关联、Matrix/嵌套条目、分页、多站点读 element-queries.md；输出任何受用户影响内容、POST 表单、JS 数据、富文本读 twig-security.md；元标签、JSON-LD、站点地图、robots.txt、hreflang 读 seomatic.md；静态缓存、“改动不显示”、缓存预热、缓存页上的动态部分读 blitz.md；构建、主题化或调试表单、垃圾提交、表单邮件不发送读 formie.md；富文本字段、富文本内嵌套条目、Redactor 转换读 ckeditor.md；DDEV 上的 Craft（craftcms 类型、ddev craft、上传目录；通用 DDEV 见 ddev-ops）读 ddev.md；模块/插件测试、fixtures、ECS/PHPStan 读 codeception.md；前端资源、Vite 开发服务器、关键 CSS 读 craft-vite.md；从 Laravel Mix/Webpack 迁移或 Vue 2 升 Vue 3 见 frontend-upgrade-ops；Craft 3 → 4 → 5 升级、插件版本线、Craft 6 状态读 upgrades.md；慢页面、图片、队列设置、生产配置读 performance.md；Core Web Vitals 失败（LCP、INP、CLS）、PageSpeed 或 Search Console 告警见 web-perf-ops；无头前端、GraphQL schema 与 token 读 graphql.md；模块、插件、事件、迁移、队列任务读 plugin-development.md；建模新的灵活页面类型读 assets/entry-type-field-layout.md。
第三步：守住底线。循环前先预加载：前面用 .with([...])，共享分部内用 .eagerly()（仅 Craft 5）；每个卡片一次查询是最常见的 Craft 性能问题。按上下文转义：绝不对受用户影响的值用 |raw；JS 字符串内用 |e('js')；每个 POST 表单加 {{ csrfInput() }}，缓存页上用 csrfInput({ async: true })。Schema 只通过 Project Config 变更：本地 CP 修改、提交 config/project/、部署时运行 php craft up；生产环境设置 allowAdminChanges => false，绝不手改 YAML。数据变更用内容迁移（php craft migrate/create），在生产副本上测试，而非在生产环境点 CP。生产环境运行队列 worker：Blitz 重新生成、Formie 邮件与集成、transform 预生成、重存都是队列任务。先修查询，再加缓存：公开页面用 Blitz；Blitz 缓存页上移除 {% cache %}（或设 enableTemplateCaching false）。逻辑放在模块服务中而非 Twig，服务可测试。保持在最新 Craft 5 补丁，Craft 会定期发布 Twig/RCE 安全修复。
版本矩阵：craftcms/cms 对应 Craft 3 为 3.9（EOL）、Craft 4 为 4.18（2026 年 4 月 EOL）、Craft 5 为 5.x（5.11，Craft 6 处于 alpha）；nystudio107/craft-seomatic 为 3.x、4.x、SEOmatic 5；putyourlightson/craft-blitz 为 3.x、4.x、Blitz 5（5.13 需要 Craft 5.6+）；verbb/formie 为 1.x、2.x、Formie 3（Formie 4 处于 beta）；富文本为 Redactor、Redactor 或 craftcms/ckeditor 3.x、CKEditor 插件 5.x（需要 Craft 5.10+，以下用 4.x）；nystudio107/craft-vite 为 1.x、4.x、craft-vite 5；nystudio107/craft-imageoptimize 为 1.x、4.x、ImageOptimize 5；spacecatninja/imager-x 为 3.x、4.x、Imager-X 6（5.x 仍在维护）；codeception/codeception 各版本与核心的 require-dev 保持一致，Craft 5 用 Codeception 5。Craft 5 要求 PHP 8.2+、MySQL 8.0.17+ / MariaDB 10.4.6+ / PostgreSQL 13+。
常用命令（本地加 ddev 前缀）：craft up 执行待处理迁移与 Project Config，每次部署都运行；craft project-config/apply 与 project-config/rebuild 将 YAML 应用到数据库或从数据库重建 YAML；craft clear-caches/all 清理数据、模板与资源缓存；craft queue/run、queue/info、queue/retry all 处理与检查队列；craft blitz/cache/refresh 在模板部署后刷新 Blitz（Blitz 跟踪内容而非模板）；craft migrate/create <name> 创建内容迁移；craft make <type> 用 craftcms/generator 脚手架生成模块/插件/组件；craft entrify/categories <group> 将分类（或标签、全局集）转换为条目。
Craft 5 内容模型：Section 为 Single、Channel 或 Structure，承载条目类型与 URI 格式；Entry type 是内容形态单元，全局且可在 section 与 Matrix 字段间复用；Field 可复用输入，全局且可在同一布局中多实例使用；Matrix 字段存储嵌套条目而非区块；CKEditor 字段可内联承载嵌套条目；元素分部 _partials/entry/<typeHandle>.twig 通过 .render() 渲染嵌套条目；Project Config（config/project/ YAML）为唯一事实来源，需提交。按形态选择 section 类型：Single 用于一次性页面（首页、联系），Channel 用于流（新闻、活动），Structure 用于层级（页面、文档）。优先采用扁平条目类型加 Matrix“页面构建器”字段，而非多个近乎相同的 section。
常见问题：列表页运行数百次查询（逐项获取关联），用 .with() / .eagerly() 修复；CP 可见但站点不显示改动（Blitz/CDN 提供缓存 HTML）；表单提交保存但邮件不发送（生产环境队列未运行）；生产环境资源无样式（Vite 5+ manifest 在 dist/.vite/，设置 manifestPath）；{% set seomatic.meta.seoTitle = ... %} 无效（set 只读，应使用 {% do seomatic.meta.seoTitle('...') %}）；站点被索引/生产被取消索引（SEOmatic 环境错误，在 view-source 检查 robots）；开发者间 Project Config 冲突（共享/生产环境 CP 编辑，本地之外 allowAdminChanges false，每次 PR 一项 schema 变更）；事件处理器每次保存触发多次（草稿、修订、传播，用 ElementHelper::isDraftOrRevision() 加 propagating 防护）；升级后 craft.matrixBlocks() 报错（Craft 5 中已移除，改用 craft.entries().field(...).owner(...)）。
捆绑资源：assets/entry-type-field-layout.md 为内容建模起步（section + 条目类型 + Matrix-as-entries，映射到 Project Config）；assets/craft-facts.json 为该技能记录的版本事实；scripts/check-craft-facts.py 为陈旧性核验器（--offline 检查文字仍陈述事实 / --live 检查 Packagist 主版本）。