该技能是 Umbraco 开发中高危错误与反模式的索引,聚焦会导致内存泄漏、不稳定、N+1 查询和性能下降的问题,事实来源为官方 Umbraco 文档。它在文档之外补充了:如何在真实代码中发现(Look for)、外部表现症状(Symptoms)、以及哪些陷阱常同时出现(Related)。每个参考文件保留简短摘要与示例,并标注其在文档页面中的章节(Docs section)。
用途与使用方式:审查或审计代码时,按 Look for 列的信号扫描代码,只打开匹配的参考文件;多个陷阱常成对出现(如 DescendantsOrSelf() 与反复调用 Model.Root()),需查看各文件末尾的 Related 链接。诊断症状(页面变慢、内存增长、数据串扰)时,先按类别匹配症状,再打开该类别的陷阱文件。编写新代码时,检查所涉及类别的陷阱,并在声称正确之前先应用修复。若参考文件示例已涵盖修复则无需抓取文档;仅当修复依赖示例未展示的内容(不同 API、边界情况或未覆盖的上下文)时,才抓取文档页面并阅读指定章节,不要凭记忆补全。
覆盖类别:依赖注入与生命周期(单例与静态、静态引用请求作用域实例);内容查询与遍历(大树上的 DescendantsOrSelf()、过度查询、Razor 视图中的服务层、未缓存昂贵查找);数据存储(易变数据存为内容节点);启动与索引(启动时昂贵处理、不必要的 Examine 索引重建、Examine 事件内服务查找);渲染(RenderTemplateAsync 用于内容渲染);模型与对象生命周期(构造函数中的逻辑、急切加载、大集合分配导致内存压力、Models Builder 误用)。
限制:官方文档页针对 Umbraco 17 和 18,是当前唯一发布的版本;底层模式适用于任意 DI 时代的 Umbraco(v9+),但文档源仅在 17/18 上验证。参考示例的 C# API 针对 Umbraco.Cms 17.5.3 与 18.2.0 编译(检查于 2026-09-23),Razor 片段通过其 C# 等价物检查,两版本均无过时 API(CS0618)警告,唯一差异是 PublishedContentWrapped 构造函数,已在 logic-in-constructors.md 中说明。截至 2026-08-05 支持版本:Umbraco 18(STS,终止支持 2027-06-25)、17(LTS,2028-11-27)、13(LTS,2026-12-14);10–12 与 14–16 已终止支持。客观断言位于 evals/evals.json,用 umbraco-skill-evaluator 运行。