Umbraco v13中Block Grid自定义首页区块不渲染问题排查

可能原因及对应解决步骤 #

1. 渲染方式与区块配置不匹配 #

你当前代码使用ViewComponent.Render，但如果区块配置的是**分部视图（Partial View）**而非ViewComponent，就会导致无法渲染。

• 检查CMS后台的区块类型配置：查看该区块的“渲染方式”选项是Partial View还是View Component。
• 若为Partial View，替换渲染代码为Umbraco官方推荐的方法：

@foreach (var block in Model.Content.Blocks)
{
    @await Umbraco.RenderBlockAsync(block)
}

• 若确实是View Component，确保已正确创建对应的ViewComponent类，且类名与区块别名匹配（遵循ASP.NET ViewComponent命名约定）。

2. 区块视图的命名/路径不符合Umbraco约定 #

即使你确认路径正确，Umbraco对区块视图的位置和命名有严格要求：

• 分部视图必须放在~/Views/Partials/BlockGrid/Blocks/目录下，文件名需与区块别名完全一致（区分大小写）。
• 若使用自定义路径，需在区块类型配置的“视图路径”字段中填写完整路径（如~/Views/CustomBlocks/MyBlock.cshtml），不能仅写文件名。

3. 模型绑定错误 #

手动渲染时若传递的模型类型不匹配，视图无法正确接收区块数据：

• 确保区块视图的模型类型正确，示例：

@model Umbraco.Cms.Core.Models.Blocks.BlockGridItem<YourCustomBlockModel>

• 优先使用Umbraco.RenderBlockAsync方法，它会自动处理模型绑定，避免手动传递模型出错。

4. 缓存或应用程序重启问题 #

Umbraco的视图缓存或应用程序池状态可能导致新视图未被加载：

• 重新生成解决方案（Visual Studio）或重启应用程序池（IIS）。
• 清空浏览器缓存，使用隐私模式测试页面。
• 检查区块视图文件的“复制到输出目录”属性，设置为如果较新则复制。

5. 页面模型未正确获取区块数据 #

若代码中Model.Content.Blocks为空，说明区块未被正确关联到页面：

• 检查首页文档类型中Block Grid属性的别名是否为Blocks，确保与代码中的Model.Content.Blocks对应。
• 调试时输出@Model.Content.Blocks.Count()，若结果为0，需确认后台页面是否已保存并发布该区块。

内容的提问来源于stack exchange，提问作者Test 1