本地开发与贡献指南

本页面面向希望在本地运行文档站、或参与内容贡献的用户和开发者。文档站基于 Docusaurus 3 构建。

环境要求

• Node.js 20+
• npm 10+

本地启动

# 克隆仓库
git clone https://github.com/overoutes/overoutes.git
cd overoutes/docusaurus

# 安装依赖（首次运行）
npm install

# 启动开发服务器（热重载）
npm run start

启动后访问 http://localhost:3000 预览文档站。

目录结构

docusaurus/
├── docs/                      # 文档内容（Markdown）
│   ├── guide/                 # 阅读须知
│   ├── airport/               # 机场板块
│   ├── vps/                   # VPS 板块
│   ├── panel/                 # 面板教程
│   ├── protocols/             # 代理协议
│   ├── clients/               # 代理软件
│   └── config/                # 配置参考
├── src/
│   ├── css/custom.css         # 全局样式与主题色
│   ├── components/            # 自定义 React 组件
│   └── pages/                 # 首页等独立页面
├── static/                    # 静态资源（图片、favicon）
├── docusaurus.config.ts       # 站点配置（导航栏、页脚、插件）
├── sidebars.ts                # 侧边栏结构定义
└── package.json

添加新页面

1. 在 docs/ 对应目录下新建 .md 文件（如 docs/vps/newprovider.md）

2. 在文件头部添加 frontmatter：

   ---
   sidebar_label: "新页面标题"
   sidebar_position: 1
   ---

3. 在 sidebars.ts 中将文件路径添加到对应分类的 items 数组

4. 如需在顶部导航栏显示，同时更新 docusaurus.config.ts 中的 navbar.items

构建与预览

# 构建生产版本
npm run build

# 本地预览构建产物
npm run serve

构建产物输出到 build/ 目录，可直接部署到任意静态托管服务。

部署

GitHub Pages（自动部署）

创建 .github/workflows/deploy.yml：

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docusaurus/build

自有服务器

将 build/ 目录的内容上传到服务器，使用 Nginx 或 Caddy 作为静态文件服务器：

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/overoutes/build;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Vercel / Netlify

Docusaurus 项目可直接导入 Vercel 或 Netlify，框架预设会自动识别构建命令和输出目录，无需额外配置。