Bootstrap 主题下用好块编辑器：六个真实踩坑与修复方案

2026年9月4日ianzhi 阅读 1

背景

WordPress 5.0 之后，古腾堡块编辑器是官方主推的内容模型。但很多站点的主题仍是经典的 Bootstrap 栅格主题（container / row / col-*），两者混用时会产生一系列「内容能存进去、前端渲染却不对」的问题。近期在为本站构建 Nextcloud 聚类页、阅读清单、关于页等落地页时踩平了六个坑，逐一记录现象、根因与修复。

坑一：wpautop 拆坏链接，渲染出空白方块

现象：用 <a> 包裹块级 <p> 做整卡链接，保存后前端出现空白方块。

根因：wpautop 过滤器会把 <a> 包裹的块级元素自闭合拆散，生成无效 HTML。

修复：不用裸 HTML 包块级元素，改用古腾堡块标记（wp:columns / wp:group）承载布局，链接放块内部。

坑二：page-no-title 模板仍然渲染双标题

现象：选了「无标题」页面模板，页面顶部却出现两个标题——主题自带的 <h1 class="page-title"> 和正文里的 H1 叠在一起。

根因：page-no-title 只是隐藏了编辑器标题栏，主题的 page-header 仍会渲染页面名。

修复：按页作用域隐藏：

body.page-id-5478 .page-header { display: none !important; }

坑三：主题写死窄栏，内容挤在左侧

现象：落地页内容被挤在左侧约 2/3 宽度，右侧是空白侧栏。

根因：Bootstrap 主题把正文放 .col-lg-8（66.67%），侧栏 .col-lg-4；块编辑器的 content-size 变量对它无效。之前针对块主题（如 Twenty Twenty-Five）的 --wp--style--global--content-size 覆盖在栅格主题上完全不生效。

修复：直接改栅格，仍然按页作用域：

body.page-id-5478 .col-lg-8 { flex: 0 0 100% !important; max-width: 100% !important; }
body.page-id-5478 .col-lg-4 { display: none !important; }
body.page-id-5478 .site-main .container { max-width: 1280px; }

坑四：wp:group 上写 grid 不生效

现象：给卡片网格容器（wp:group + 自定义类）设 display: grid，卡片全部竖直堆叠贴左。

根因：古腾堡的 wp:group 会在内容外自动包一层 wp-block-group__inner-container。grid 作用在外层时，它唯一的网格子项是 inner-container，真正的卡片是孙节点，根本没进网格。

修复：grid 必须命中内层容器：

body.page-id-5478 .nc-grid > .wp-block-group__inner-container {
  display: grid !important;
  grid-template-columns: repeat(3, 1fr);
}

坑五：后代选择器穿透，卡片内容左右分列

现象：修完坑四后，网格排好了，但每张卡片内部的标题和正文变成了左右两列。

根因：修复坑四时若写成后代选择器 .nc-grid .wp-block-group__inner-container（空格），它会一路穿透到底，把每张卡片自己的 inner-container 也设成网格——卡片里恰好只有 h3 和 p 两个元素，被分进两个格子。

修复：改用子选择器 >（如坑四代码），只命中网格直接内层，卡片内部保持块流。

坑六：REST API 发大正文报 411

现象：Node 通过 REST API 发布整篇文章，小请求正常，大正文请求被 WAF 直接拒掉 411 Length Required。

根因：https.request 不设 Content-Length 时走 chunked 传输，WAF 层拒绝。

修复：显式设置请求头，且注意合并顺序不能被覆盖：

const payload = JSON.stringify(body);
const headers = Object.assign({ Authorization: AUTH, 'Content-Type': 'application/json' }, opts.headers);
headers['Content-Length'] = Buffer.byteLength(payload);  // 必须在合并之后设置
const r = https.request(Object.assign({}, opts, { hostname, headers }), ...);

落地规范总结

正文一律用标准块（wp:heading / wp:paragraph / wp:group / wp:columns / wp:buttons / wp:list），禁止整页塞进单个 wp:html 裸块；自定义样式收敛到一个 wp:html 的 <style> 块。
所有覆盖样式按页作用域（body.page-id-xxx），避免波及全站。
对 wp:group 做布局时选择器必须命中 inner-container，且用 > 子选择器防止穿透。
先确认主题类型再动手：栅格主题改 col-*，块主题改 content-size 变量——用错模型会白折腾。

这套规范落地后，本站的聚类页与落地页在块编辑器里可正常按块编辑，前端渲染也与设计一致。本站 Nextcloud 聚类页即是按此规范构建的完整示例。

参考文档

WordPress.org. Block Editor Handbook[EB/OL]. https://developer.wordpress.org/block-editor/ (访问日期: 2026-09-04).
WordPress.org. Layout Grid and Container Blocks: Group[EB/OL]. https://wordpress.org/documentation/article/group-block/ (访问日期: 2026-09-04).

标签：CSS Gutenberg WordPress

ianzhi

背景