HTMLHeaderTextSplitter 必须显式配置 headers_to_split_on 才能避免OOM，需设为[("h1","title"),("h2","section"),("h3","subsection")]并启用return_each_element=True以保留标题路径；含表格或代码的页面应改用HTMLSemanticPreservingSplitter。
HTMLHeaderTextSplitter 不配 headers_to_split_on 就会OOM
门户网站的文档结构天然多级，HTMLHeaderTextSplitter 默认只切 h1，漏掉 h2 或 h3 会导致整块吞并——比如一个含 12 个 h2 节的长页被当成单个 600KB 块处理，向量化直接卡死或触发内存溢出（OOM）。
- 必须显式传入
headers_to_split_on=[("h1", "title"), ("h2", "section"), ("h3", "subsection")] - 若需保留每个
<p>所属的标题路径（如用于上下文溯源），得加return_each_element=True - 含
<table>或<pre><code>的页面别硬用它——表格跨行、代码换行会被截断，应换HTMLSemanticPreservingSplitter
art-template block 命名冲突会让中间层继承失效
大型门户常用三层继承：layout.art → inner-layout.art → page.art。但只要任意两层定义同名 {{block 'content'}}，最末层就会覆盖中间层的插入点，导致导航栏、侧边栏等区域内容丢失。
- block 名必须全局唯一且带职责前缀，例如
'header-nav'、'main-hero'、'sidebar-recommend' - 所有 block 名建议统一维护在根目录
blocks.json中，供构建脚本校验是否存在重复 - 继承链超过三层（layout → inner → feature → detail）会显著降低编译缓存命中率，调试时也难定位哪一层改坏了
非首屏 HTML 不能用 display: none
display: none 的区块仍参与 DOM 构建、CSSOM 计算和内存分配，只是不绘制——对商品列表页后半截、长图文页滚动区，这会让首屏解析拖慢 300ms+，FCP 直接超标。
- 真实懒加载必须用
<template>标签包裹非首屏片段，配合IntersectionObserver动态挂载 - 内联 CSS 只允许首屏关键样式，且必须声明
media属性（如media="print"或media="(max-width: 768px)"） - 服务端渲染（SSR）时，
<template>内容不输出 HTML，避免冗余传输
语义化替换不是搜索替换，而是契约重写
把 <div class="main"> 改成 <main> 看似简单，但浏览器和辅助技术会按严格契约校验：比如 <main> 页面只能有一个，<section> 必须有可访问标题，<nav> 不能塞面包屑。
立即学习“前端免费学习笔记（深入）”；
-
document-multiple-main-elements是 Lighthouse 硬性报错项，哪怕其中一个<main>在<dialog>里也会被扫到 - 面包屑、分页应放
<ol role="navigation">或<nav aria-label="Pagination">，而非裸<nav> - 所有语义标签必须闭合；
<header>不能是<main>的子元素却漏掉</header>，否则 SSR/CSR 渲染不一致
block 名可能让三处页面失焦，换一个 <main> 标签可能触发无障碍审查失败。这些地方没有报错，只有上线后用户反馈“导航不见了”或“读屏器念错顺序”，得靠提前约定和自动化校验兜底。 
