HTML组件化开发：基于Pug模板引擎的高效维护指南-html教程-PHP中文网

pug 的 include 是编译时静态嵌入，实现真正组件复用需确保路径正确（相对于当前文件）、仅支持 .pug 文件、配合 mixin 隔离作用域传参，并在 webpack 中配置 dependon 或 watchoptions 以触发重编译。

html组件化开发：基于pug模板引擎的高效维护指南

Pug 的 include 不是简单复制粘贴，而是编译时的静态嵌入。这意味着被包含文件（如 src/pug/includes/navbar.pug）一旦修改，所有引用它的页面都会同步更新——但前提是路径写对、且没被缓存干扰。

路径必须相对于当前 Pug 文件，不是相对于项目根目录：
include includes/navbar.pug ✅（当前文件在 src/pug/ 下）
include src/pug/includes/navbar.pug ❌（会报 Failed to resolve include）
include 只支持 .pug 文件，不能直接 include HTML 或 JS；若需动态内容，得用 block + extends 配合 layout
Webpack 场景下，pug-loader 默认不监听被 include 的文件变更，需手动配置 dependOn 或启用 watchOptions，否则改了 footer.pug 但页面没刷新，容易误判为“没生效”

二者解决不同问题：include 是“拼接”，extends 是“继承”。选错会导致逻辑混乱或编译失败。

用 include：
- 多个页面共用同一段结构（如导航栏、页脚）
- 组件无逻辑依赖，纯 UI 片段（portfolio-modal-1.pug 就属于这类）
- 不需要传参或上下文隔离
用 extends：
- 页面有统一骨架（比如 layout/main.pug 定义 head、body、footer 区域）
- 子模板通过 block content 注入差异化内容
- 需要复用布局逻辑（如 SEO meta 标签、全局 script 加载顺序）
混用常见错误：在 extends 的子模板里又 include 同一个 layout 文件，会造成重复渲染或编译报错 Cannot overwrite block

这不是缓存错觉，而是三个典型原因叠加的结果：

Markdown to HTML

{"answer":"将 Markdown 转换为内嵌 CSS、样式精美的独立 HTML。完美适用于新闻简报、文档、报告及邮件模板。"}

下载

pug-loader 默认关闭 pretty 选项时，生成的 HTML 是单行压缩格式，diff 工具难识别变化，建议开发期始终开启：
{ loader: 'pug-loader', options: { pretty: true } }
Webpack 的持久化缓存（cache: true）可能跳过未声明依赖的 included 文件，需显式告诉它：“这个文件变了，也要重编译主模板”：
include 语句本身不会触发父模板重编译，除非你用 require('./includes/header.pug') 这种方式（但会失去 Pug 原生语法优势）
某些构建脚本（如 html-webpack-plugin）默认只监听 template 指定的入口文件，不递归 watch 所有 include 路径。解决方案是加 files: ['src/pug/*<em>\/</em>.pug'] 到 webpack watch 配置中

Pug 本身不支持函数式参数传递，所谓“传参”本质是作用域变量注入，容易踩坑：

include 不带参数：所有变量来自父作用域，父子模板共享同一变量名空间 → 改 title 可能意外覆盖子组件里的 title
正确做法是用 mixin：
```
mixin card(title, content)
.card
  h3= title
  p= content
```
调用：+card('Hello', 'World')
mixin 是唯一能隔离作用域的方式，但注意：它不能跨文件复用，必须定义在同一个文件里，或通过 include 引入含 mixin 的文件
若需跨文件传参（如从 index.pug 向 includes/post-list.pug 传 posts 数组），只能靠父模板提前 assign 变量，再在被 include 文件里直接使用 —— 这要求双方约定好变量名，没有类型检查，出错时错误信息指向 include 行，而非实际赋值处