vite-pug-static-builder
Version:
Vite + Pugを使用した静的サイトビルダー - 複数のPugファイルを静的HTMLとしてビルドするViteプラグイン
358 lines (285 loc) • 7.83 kB
Markdown
# vite-pug-static-builder
[](./LICENSE)
[](https://www.typescriptlang.org/)
[](https://vitejs.dev/)
[](https://pugjs.org/)
[](https://vitest.dev/)
**[English](./README.md)** | **[日本語](./README.ja.md)**
**兼容 Vite 6 / 7 / 8** — 基于 Vite + Pug 的高性能静态站点构建器
一个现代化的 Vite 插件，可以高效地将多个 Pug 文件构建为静态 HTML 文件。
支持 Vite 6、7 和 8。
## ✨ 特性
- 🚀 **快速构建**：基于 Vite 构建系统的高速开发体验
- 📝 **Pug 支持**：使用 Pug 模板引擎高效编写 HTML
- 🔄 **实时更新**：开发时支持 HMR（热模块替换）
- 📱 **静态站点生成**：生成面向生产环境优化的静态 HTML 文件
- 🎨 **高度可定制**：丰富的配置选项，适配各种项目需求
- 🛡️ **类型安全**：完整的 TypeScript 支持，提前发现开发错误
## 安装
```bash
# npm
npm install vite-pug-static-builder
# yarn
yarn add vite-pug-static-builder
# pnpm
pnpm add vite-pug-static-builder
```
## 环境要求
- **Node.js**：18.0.0 或更高版本
- **Vite**：^6.0.0 || ^7.0.0 || ^8.0.0
- **Pug**：^3.0.0
## 基本用法
### 1. Vite 配置文件
```typescript
// 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 文件示例
```pug
//- src/index.pug
extends _layouts/base
block content
main
h1= title
p 欢迎来到 #{title}！
if env === 'development'
.dev-info 正在开发模式下运行
include _includes/header
```
## 配置选项
### 插件配置
```typescript
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
}
}
```
### Pug 选项默认值
`build.options` 和 `serve.options` 应用以下默认设置：
- **`pretty`**：默认为 `true`（在 Pug 3.x 中已弃用）
用户在 `options` 中指定的值会覆盖默认值。
### 高级配置
```typescript
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
}
})
```
## 开发命令
```bash
# 启动开发服务器
npm run dev
# 生产构建
npm run build
# 预览构建
npm run preview
# 类型检查
npm run type-check
# 运行测试（Vite 8 环境）
npm test
# 在 Vite 6 / 7 环境下运行测试
npm run test:vite6
npm run test:vite7
# 带覆盖率的测试
npm run coverage
# 监听模式
npm run test:watch
```
## TypeScript 集成
完整的 TypeScript 支持确保配置文件和 Pug 模板的类型安全：
```typescript
// 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
}
```
## 性能优化
```typescript
pugPlugin({
build: {
options: {
cache: true, // 启用缓存
inlineRuntimeFunctions: false, // 外部化运行时函数
compileDebug: false // 移除调试信息
}
},
serve: {
options: {
cache: false, // 开发时禁用缓存
compileDebug: true // 开发时启用调试
}
}
})
```
## 故障排除
### 常见问题
**Q：Pug 文件更新后浏览器没有刷新**
```typescript
pugPlugin({
serve: {
reload: true
}
})
```
**Q：构建时 Pug 依赖关系未正确解析**
```typescript
pugPlugin({
build: {
options: {
basedir: path.resolve(__dirname, 'src')
}
}
})
```
**Q：开发服务器中的错误处理**
```pug
//- 检查变量是否存在以防止错误
if typeof title !== 'undefined'
h1= title
else
h1 Default Title
```
## 迁移指南
### 从其他 Pug 插件迁移
```diff
- 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](./LICENSE) © 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.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](https://vitejs.dev/)
- [Pug](https://pugjs.org/)
- [GitHub Repository](https://github.com/ozekimasaki/vite-pug-static-builder)