Bigcommerce子类别自定义模板不生效问题求助

数据老陈

2026-7-17

Bigcommerce自定义子类别模板不生效排查步骤

检查config.stencil.json配置格式
确认customLayouts的结构和路径配置正确，注意模板路径不要带.html后缀，且子类别路径要和后台完全匹配：
```
"customLayouts": {
  "category": {
    "/3d-series/": "custom/category/_category-3d-series"
  }
}
```
Bigcommerce路径区分大小写，拼写、斜杠都要和后台子类别URL一致。
验证模板文件路径与命名
确保文件放在templates/pages/custom/category/目录下，文件名为_category-3d-series.html——自定义模板必须以下划线开头，这是Stencil的命名规范。
清理Stencil缓存
旧缓存可能导致模板不加载，先执行：
```
stencil clean
```
再重新启动服务：
```
stencil start
```
核对后台子类别URL
登录Bigcommerce后台，找到目标子类别，查看其「URL」设置，确认前台访问路径确实是/3d-series/，没有多余前缀、拼写错误或大小写差异。

检查模板内容与继承
确保模板正确继承基础布局，且标识文本放在可见区域：

{{#partial "page"}}
<div style="color:red;font-size:20px;">3D系列自定义模板标识</div>
<!-- 其他自定义内容 -->
{{/partial}}
{{> layout/base}}

不要把标识放在注释或被隐藏的元素内。

更新Stencil CLI到稳定版
运行以下命令检查版本，旧版本可能存在兼容问题：
```
stencil --version
```
如需更新，执行：
```
npm install -g @bigcommerce/stencil-cli
```
确认本地访问路径
启动本地服务后，直接访问http://localhost:3000/3d-series/，不要附加其他参数或路径。