HTMLHeaderTextSplitter需显式配置headers_to_split_on为h1-h3三级标题，否则导致块过大或OOM；含表格/代码应换用HTMLSemanticPreservingSplitter；art-template block命名须全局唯一且语义化，避免多层继承覆盖；非首屏内容用<template>配合IntersectionObserver按需加载；内联CSS仅限首屏关键样式并声明media属性。
HTMLHeaderTextSplitter 必须显式配置 headers_to_split_on
默认只切 h1，但门户网站的文档往往有 h1–h3 多级语义结构。漏配任何一级，对应层级就完全失效，比如 h2 节块被吞进上一个 h1 块里，导致单块超 500KB、向量化失败或渲染 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 再继承 inner-layout。如果多个子模板都定义了同名 {{block 'content'}}，上级 layout 中的 {{block 'content'}} 就会被最末层覆盖，中间层的插入点失效。
推荐做法：
立即学习“前端免费学习笔记（深入）”；
- 按区域+职责命名，如
'header-nav'、'main-hero'、'sidebar-recommend' - 所有
block名在项目根目录下统一维护成 JSON 配置，供构建脚本校验 - 避免嵌套过深——超过三层继承（layout → inner → feature → detail）会导致调试困难、编译缓存命中率骤降
非首屏 HTML 片段必须用 <template> 而非 display: none
display: none 的区块仍参与 DOM 构建和 CSSOM 计算，只是不绘制；对商品列表页、长图文页后半截内容，这会显著拖慢首屏解析速度。
正确做法是：
- 把评论区、相关推荐等移入
<template id="comments">...</template> - 用
IntersectionObserver监听进入视口后，调用template.content.cloneNode(true)插入真实 DOM - 禁用
innerHTML = fetch(...).then(r => r.text())方式——它会执行内联脚本、绕过 CSP、SSR 不友好
内联关键 CSS 只允许用于首屏且必须声明 media
门户网站首页 hero 区、导航栏、搜索框等首屏必需样式可以内联，但必须带 media="screen" 或 media="screen and (min-width: 0px)"，否则浏览器会阻塞渲染等待其他 CSS 加载完成。
常见错误：
- 把整个
main.css内联，HTML 体积暴涨，在弱网下反而更慢 - 内联样式里写
@import或@font-face，它们仍触发额外请求并阻塞 - 用
<style>替代<link rel="stylesheet">管理通用组件样式，破坏缓存复用和 CI/CD 提取逻辑
真正难处理的不是“怎么拆”，而是“谁来保证拆完之后的锚点 ID 不冲突、语义层级不塌陷、动态加载时 script 执行时机不漂移”——这些必须靠构建时校验 + 运行时 guard 机制兜底，不能靠人工 review。
