VuePress Template

一个开箱即用的 VuePress 2 文档模板

快速开始插件参考

模块化配置

site / head / theme / navbar / sidebar / plugins 拆分为独立文件，config.ts 仅做聚合。

工程化工具链

ESLint + Prettier + husky + commitlint + vue-tsc 类型检查 + GitHub Actions CI 开箱即用。

官方插件精选

shiki 高亮、搜索、PWA、GA4、DocSearch、sitemap、自定义容器按需启用，未配置不影响构建。

双部署目标

Cloudflare 与 GitHub Pages 一套代码，base 由环境变量驱动，切换免改代码。

PWA 离线可安装

自动生成 manifest 与 service worker，含 192/512 图标，支持离线访问与「安装到桌面」。

示例文档齐全

内置 Markdown 语法速查与「如何编写 VuePress 插件」范例，开箱即学。

快速上手

pnpm install      # 安装依赖
pnpm dev          # 启动开发服务器
pnpm build        # 构建静态站点
pnpm typecheck    # 类型检查（vue-tsc）
pnpm lint         # 代码规范检查并修复
pnpm format       # Prettier 格式化

提示

本模板基于 VuePress 2（Vue 3 技术栈），全链路 TypeScript，配置由环境变量驱动。

部署

base 与 SITE_URL 由环境变量驱动，一套代码支持两种托管方式，切换免改代码。

方式一：Cloudflare Workers（根路径，默认）

仓库已含 wrangler.toml（声明静态资源目录 .vuepress/dist）。在 Cloudflare 控制台创建 Workers 项目并连接 Git 仓库：

  • 构建命令：pnpm run build
  • 部署命令：npx wrangler deploy
  • 根目录：/

推送即部署，base 默认 /，无需额外配置。

方式二：GitHub Pages（子路径）

仓库已含 .github/workflows/deploy.yml：推送到 main 自动构建（已注入 BASE=/vuepress-template/）并部署到 GitHub Pages，无需 Secret。

  1. 仓库 Settings → Pages → Source 选 GitHub Actions。
  2. 推送：git push origin main
  3. 访问：https://<用户名>.github.io/vuepress-template/（仓库名不同请改 workflow 里的 BASE）

两种方式可并存：GitHub Actions 用 BASE=/repo/ 构建发 GitHub Pages，Cloudflare Git 集成用默认 / 构建，互不干扰。

可选：DocSearch / GA / sitemap

构建时注入环境变量即可启用，未配置则跳过：

SITE_URL=https://example.com \        # 生成 sitemap / canonical / OG
GA_ID=G-XXXXXXXXXX \                  # GA4 统计
DOCSEARCH_APP_ID=... DOCSEARCH_API_KEY=... DOCSEARCH_INDEX_NAME=... \  # Algolia 搜索
pnpm build

完整变量见 .env.example。

MIT Licensed | Copyright © 2026