vite-pug-static-builder

English | 日本語

兼容 Vite 6 / 7 / 8 — 基于 Vite + Pug 的高性能静态站点构建器

一个现代化的 Vite 插件，可以高效地将多个 Pug 文件构建为静态 HTML 文件。 支持 Vite 6、7 和 8。

✨ 特性

• 🚀 快速构建：基于 Vite 构建系统的高速开发体验
• 📝 Pug 支持：使用 Pug 模板引擎高效编写 HTML
• 🔄 实时更新：开发时支持 HMR（热模块替换）
• 📱 静态站点生成：生成面向生产环境优化的静态 HTML 文件
• 🎨 高度可定制：丰富的配置选项，适配各种项目需求
• 🛡️ 类型安全：完整的 TypeScript 支持，提前发现开发错误

安装

# npm
npm install vite-pug-static-builder

# yarn
yarn add vite-pug-static-builder

# pnpm
pnpm add vite-pug-static-builder

环境要求

• Node.js：20.19.0 或更高版本（或 22.12.0+）
• Vite：^6.0.0 || ^7.0.0 || ^8.0.0
• Pug：^3.0.0

基本用法

1. Vite 配置文件

// vite.config.ts
import { defineConfig } from 'vite'
import pugPlugin from 'vite-pug-static-builder'

export default defineConfig({
  plugins: [
    pugPlugin({
      build: {
        options: {
          basedir: './src'
        },
        locals: {
          title: 'My Website',
          env: 'production'
        }
      },
      serve: {
        options: {
          basedir: './src'
        },
        locals: {
          title: 'My Website (Dev)',
          env: 'development'
        }
      }
    })
  ]
})

2. 项目结构示例

src/
├── index.pug          # → dist/index.html
├── about/
│   └── index.pug      # → dist/about/index.html
├── blog/
│   ├── index.pug      # → dist/blog/index.html
│   └── post1.pug      # → dist/blog/post1.html
├── _layouts/
│   └── base.pug       # 布局模板
├── _includes/
│   └── header.pug     # 局部模板
└── assets/
    ├── style.css
    └── script.js

3. Pug 文件示例

//- src/index.pug
extends _layouts/base

block content
  main
    h1= title
    p 欢迎来到 #{title}！
    
    if env === 'development'
      .dev-info 正在开发模式下运行
    
    include _includes/header

配置选项

插件配置

interface Settings {
  // 构建设置
  build?: {
    // Pug 编译选项
    options?: Pug.Options
    // Pug 局部变量
    locals?: Pug.LocalsObject
  }

  // 开发服务器设置
  serve?: {
    // Pug 编译选项
    options?: Pug.Options
    // Pug 局部变量
    locals?: Pug.LocalsObject
    // 忽略模式（glob 格式）
    ignorePattern?: string | string[]
    // 热重载（默认：true）
    reload?: boolean
  }
}

HTML 格式化

Pug 3 已移除 pretty 选项。本插件不会重新缩进编译后的 HTML。 如需可读输出，请在项目中格式化 dist/**/*.html。

buildOptions 和 watch 仍可作为 build.options / serve.options 与 serve.reload 的别名使用，但会输出弃用警告。

高级配置

pugPlugin({
  build: {
    options: {
      basedir: './src',
      compileDebug: false,
      cache: true,
      inlineRuntimeFunctions: false
    },
    locals: {
      title: 'Production Site',
      version: process.env.npm_package_version,
      buildTime: new Date().toISOString(),
      author: 'Your Name',
      description: 'A modern static site built with Vite and Pug'
    }
  },
  serve: {
    options: {
      basedir: './src',
      compileDebug: true,
      cache: false
    },
    locals: {
      title: 'Development Site',
      version: 'dev',
      buildTime: 'dev-mode'
    },
    ignorePattern: [
      '/_*/**',            // 忽略以下划线开头的目录
      '/admin/**',         // 忽略 admin 目录
      '/**/*.draft.pug'    // 忽略 .draft.pug 文件
    ],
    reload: true
  }
})

开发命令

# 启动开发服务器
npm run dev

# 生产构建
npm run build

# 预览构建
npm run preview

# 类型检查
npm run type-check

# 在 Vite 6 / 7 / 8 环境下运行测试
npm test

# 仅针对某个 Vite 大版本运行测试
npm run test:vite6
npm run test:vite7
npm run test:vite8

# 带覆盖率的测试
npm run coverage

# 监听模式
npm run test:watch

TypeScript 集成

完整的 TypeScript 支持确保配置文件和 Pug 模板的类型安全：

// types/pug.d.ts
declare module '*.pug' {
  const content: string
  export default content
}

// vite-env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  readonly VITE_API_URL: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

性能优化

pugPlugin({
  build: {
    options: {
      cache: true,                   // 启用缓存
      inlineRuntimeFunctions: false, // 外部化运行时函数
      compileDebug: false            // 移除调试信息
    }
  },
  serve: {
    options: {
      cache: false,        // 开发时禁用缓存
      compileDebug: true   // 开发时启用调试
    }
  }
})

故障排除

常见问题

Q：Pug 文件更新后浏览器没有刷新

pugPlugin({
  serve: {
    reload: true
  }
})

Q：构建时 Pug 依赖关系未正确解析

pugPlugin({
  build: {
    options: {
      basedir: path.resolve(__dirname, 'src')
    }
  }
})

Q：开发服务器中的错误处理

//- 检查变量是否存在以防止错误
if typeof title !== 'undefined'
  h1= title
else
  h1 Default Title

迁移指南

从其他 Pug 插件迁移

- import { createPugPlugin } from 'vite-plugin-pug'
+ import pugPlugin from 'vite-pug-static-builder'

- createPugPlugin({
-   pugOptions: { basedir: './src' }
- })
+ pugPlugin({
+   build: {
+     options: { basedir: './src' }
+   },
+   serve: {
+     options: { basedir: './src' }
+   }
+ })

许可证

MIT © 2025 maigo999

贡献

欢迎提交 Pull Request 和 Issue！

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

更新日志

v1.3.1

• 将 Vite 模块 ID 规范为 POSIX，使 Windows 上 resolveId / load 共用同一 pathMap
• 根目录 Pug 现在映射为 /index.html，不再是 //index.html
• CI 在 Ubuntu、macOS 和 Windows 上运行

v1.3.0

• 模块图仍有有效 transform 时不再重新编译 Pug
• 用 path.resolve 解析 HTML 请求路径（兼容 Windows）
• 并行检查 HTML / Pug 是否存在；忽略非 GET/HEAD
• applyToEnvironment 仅作用于 client 环境
• build --watch 期间缓存编译结果，.pug 变更时丢弃
• include / extends 在可用时通过 createFileOnlyEntry 注册
• 使用 Vite 的 config.logger，尊重 logLevel: 'silent'

v1.2.0

• 停止应用 Pug 2 的 pretty: true 默认值（Pug 3 已移除）
• 开发服务器对缺失 HTML 返回 HTTP 404
• 仅在 Pug 或其 include / extends 变更时执行 full reload
• 构建时监视 Pug 依赖文件
• buildOptions / watch 作为已弃用别名保留
• 更新 pug 3.0.4、TypeScript 7.0.2 以及 Vite 8 / picomatch 类型

v1.1.5 (2026-03-13)

• 🌐 添加多语言 README（英语、日语、中文）

v1.1.4 (2026-03-13)

• 📝 修正 README 使其与实际 API 实现一致

v1.1.3 (2026-03-13)

• 🚀 支持 Vite 8
• 📦 将 @types/node 添加到 devDependencies

v1.1.2

• 🚀 支持 Vite 7 稳定版
• 🧪 支持 Vitest 3.2

v1.0.0

• 🚀 首次发布
• ✨ 支持 Environment API
• 🛡️ 完整的 TypeScript 支持

相关链接

• Vite
• Pug
• GitHub Repository