开发指南

本文档面向 HealthGuard 官网的贡献者，说明本地开发、构建和部署的完整流程。

环境要求

• Node.js: >= 18.0.0
• npm: >= 9.0.0（本仓库使用 npm）

快速开始

# 克隆官网仓库
git clone https://github.com/Claud-Lu/healthguard-website.git
cd healthguard-website

# 安装依赖
npm install

# 启动开发服务器
npm run dev

开发服务器默认运行在 http://localhost:5173。

常用命令

命令	说明
npm run dev	启动开发服务器，支持热更新
npm run build	构建生产版本，输出到 .vitepress/dist/
npm run preview	预览构建结果（需先执行 build）
npm run lint	TypeScript 类型检查（tsc --noEmit）

项目结构

healthguard-website/
├── .github/workflows/      # CI/CD（GitHub Actions）
├── .vitepress/
│   ├── config.ts           # 站点配置（导航、侧边栏、多语言）
│   ├── theme/
│   │   ├── index.ts        # 主题入口
│   │   ├── Layout.vue      # 自定义布局（首页/文档页切换）
│   │   └── style.css       # 品牌样式覆盖
│   └── dist/               # 构建输出（gitignore）
├── src/
│   └── components/         # Vue 组件（首页自定义区块）
│       ├── home/           # 首页组件
│       └── shared/         # 共享组件
├── zh/                     # 中文内容
├── en/                     # 英文内容（与 zh/ 镜像结构）
├── public/                 # 静态资源（Logo、截图、OG 图）
├── package.json
├── tsconfig.json
└── README.md

内容编辑 workflow

新增一篇文档

以新增"部署指南"为例：

1. 创建文件 zh/guide/deployment.md
2. 添加 frontmatter：

   ---
   title: 部署指南
   description: 使用 Docker Compose 私有化部署 HealthGuard
   ---

3. 编写正文（Markdown）
4. 在 .vitepress/config.ts 的 sidebar 中注册链接
5. 同步创建英文版本 en/guide/deployment.md
6. 在英文 sidebar 中同步注册

编辑首页

首页组件位于 src/components/home/，修改对应 Vue 文件即可。

添加图片

1. 将图片放入 public/ 目录
2. 在 Markdown 或 Vue 中通过 /xxx.png 引用

多语言同步 checklist

每次修改文档后，按此清单检查：

• [ ] 中文文档已更新
• [ ] 英文文档已同步更新
• [ ] .vitepress/config.ts 中的中英文 sidebar 已同步
• [ ] 首页文案（如涉及）已同步
• [ ] 本地开发服务器可正常访问两个语言版本

提交规范

本项目采用 Conventional Commits：

feat: 新增功能
docs: 文档更新
fix: 修复 bug
style: 样式调整
refactor: 代码重构

部署前检查清单

• [ ] npm run build 无报错
• [ ] npm run lint 无类型错误
• [ ] 所有页面在 npm run preview 下正常显示
• [ ] 中英文切换正常
• [ ] 移动端视图正常
• [ ] 所有外部链接可正常访问