Swit 框架

中文

English

中文

English

Appearance

网站开发指南 ​

本文档为基于VitePress构建的Swit项目GitHub Pages网站的开发和维护提供全面指导。

概述 ​

Swit项目网站使用以下技术构建：

  • VitePress - 静态站点生成器
  • Vue 3 - 组件框架
  • TypeScript - 类型安全
  • Tailwind CSS - 样式框架
  • GitHub Actions - CI/CD 流水线

项目结构 ​

docs/pages/
├── .vitepress/           # VitePress 配置
│   ├── config/          # 多语言配置
│   └── theme/           # 自定义主题组件
├── en/                  # 英文内容
├── zh/                  # 中文内容
├── public/              # 静态资源
├── scripts/             # 构建和自动化脚本
└── tests/               # 测试套件

开发环境设置 ​

环境要求 ​

  • Node.js 18+
  • npm 或 yarn
  • Git

安装步骤 ​

bash
cd docs/pages
npm install

开发命令 ​

bash
# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

# 运行测试
npm test

# 运行代码检查
npm run lint

# 类型检查
npm run type-check

网站架构 ​

VitePress 配置 ​

网站采用多语言设置，包含共享配置：

  • config/index.mjs - 主配置入口
  • config/shared.mjs - 共享设置
  • config/en.mjs - 英文特定配置
  • config/zh.mjs - 中文特定配置

主题自定义 ​

自定义主题组件位于 .vitepress/theme/：

  • index.js - 主题入口点
  • components/ - Vue 组件
  • styles/ - CSS 样式和变量

内容结构 ​

内容按语言和类别组织：

├── en/zh/
│   ├── index.md          # 首页
│   ├── guide/            # 用户指南
│   ├── api/              # API文档
│   ├── examples/         # 代码示例
│   └── community/        # 社区资源

组件开发 ​

创建新组件 ​

  1. 在 .vitepress/theme/components/ 中创建Vue组件
  2. 在主题 index.js 中导入和注册
  3. 在Markdown文件中使用，传递适当的属性

组件结构示例：

vue
<template>
  <div class="my-component">
    <!-- 组件内容 -->
  </div>
</template>

<script setup lang="ts">
// TypeScript 设置
</script>

<style scoped>
/* 组件样式 */
</style>

核心组件 ​

  • HomePage.vue - 首页英雄区和特性展示
  • FeatureCard.vue - 特性展示卡片
  • CodeExample.vue - 语法高亮代码示例
  • ApiDocViewer.vue - API文档显示
  • SearchBox.vue - 增强搜索功能

样式指南 ​

  • 使用Tailwind CSS类保持一致性
  • 遵循响应式设计原则
  • 支持浅色和深色主题
  • 维护无障碍访问标准

内容管理 ​

编写文档 ​

  1. 使用带VitePress扩展的Markdown
  2. 在frontmatter中包含标题和描述
  3. 遵循既定的内容结构
  4. 添加适当的导航链接

多语言支持 ​

  • 保持语言间内容结构一致
  • 使用相同的文件名和路径
  • 同时更新两种语言版本
  • 测试语言切换功能

内容自动化 ​

网站包含自动化内容管理脚本：

  • sync-docs.js - 从主项目同步内容
  • api-docs-generator.js - 生成API文档
  • content-validator.js - 验证内容一致性

API文档集成 ​

自动生成 ​

API文档从以下来源自动生成：

  • OpenAPI/Swagger规范
  • Protocol Buffer定义
  • 代码注释和注解

手动更新 ​

手动更新API文档：

  1. 编辑主项目中的源文件
  2. 运行 npm run sync:api 重新生成
  3. 审查并提交更改

性能优化 ​

构建优化 ​

  • 自动配置代码分割
  • 构建时优化静态资源
  • CSS清理和最小化

运行时性能 ​

  • 图片使用懒加载
  • 关键资源预加载
  • Service Worker提供离线缓存

监控 ​

性能监控使用：

  • GitHub Actions中的Lighthouse CI
  • Core Web Vitals跟踪
  • 包大小分析

测试策略 ​

单元测试 ​

bash
# 运行组件测试
npm run test:unit

# 监视模式
npm run test:unit:watch

# 覆盖率报告
npm run test:coverage

端到端测试 ​

bash
# 运行端到端测试
npm run test:e2e

# 无头模式运行
npm run test:e2e:headless

无障碍访问测试 ​

bash
# 运行无障碍访问审计
npm run test:a11y

性能测试 ​

bash
# 运行性能审计
npm run test:performance

部署 ​

GitHub Actions ​

网站通过GitHub Actions自动部署：

  1. 构建阶段 - 编译VitePress站点
  2. 测试阶段 - 运行所有测试套件
  3. 部署阶段 - 发布到GitHub Pages

手动部署 ​

手动部署：

bash
# 构建生产站点
npm run build

# 部署到GitHub Pages
npm run deploy

维护任务 ​

定期更新 ​

  • 每月更新依赖项
  • 每季度审查和更新内容
  • 每周监控性能指标
  • 每月检查断链

内容同步 ​

bash
# 与主项目文档同步
npm run sync:docs

# 更新API文档
npm run sync:api

# 验证内容一致性
npm run validate:content

安全更新 ​

  • 监控安全公告
  • 及时更新依赖项
  • 定期运行安全审计

故障排除 ​

常见问题 ​

构建失败

  • 检查Node.js版本兼容性
  • 清除node_modules并重新安装
  • 验证配置文件语法

开发服务器问题

  • 检查端口可用性（默认5173）
  • 清除VitePress缓存
  • 验证文件权限

内容显示问题

  • 检查Markdown语法
  • 验证frontmatter格式
  • 测试组件导入

性能问题

  • 分析包大小
  • 检查图片优化
  • 审查懒加载实现

调试模式 ​

启用调试模式获取详细日志：

bash
DEBUG=vitepress:* npm run dev

贡献指南 ​

代码风格 ​

  • 遵循TypeScript最佳实践
  • 使用ESLint和Prettier配置
  • 编写有意义的提交信息
  • 为新功能包含测试

拉取请求流程 ​

  1. 创建功能分支
  2. 进行更改并编写测试
  3. 运行完整测试套件
  4. 提交带描述的PR
  5. 处理审查反馈

文档标准 ​

  • 编写清晰、简洁的文档
  • 包含代码示例
  • 保持两种语言版本更新
  • 遵循既定模式

版本控制 ​

分支策略 ​

  • master - 主分支
  • docs/development - 活跃开发
  • docs/gh-pages - 部署分支
  • 特定更改的功能分支

发布流程 ​

  1. 更新版本号
  2. 运行完整测试套件
  3. 构建生产站点
  4. 标记发布
  5. 部署到生产环境

支持和资源 ​

获取帮助 ​

  • 查看现有文档
  • 搜索GitHub问题
  • 创建详细错误报告
  • 参与社区讨论

有用资源 ​

联系方式 ​

  • 为错误创建GitHub问题
  • 使用讨论区提问
  • 遵循贡献指南
  • 尊重社区标准

Released under the MIT License.

Copyright © 2025 Swit Framework Contributors