部署指南

本指南介绍如何将 AutoDoc 文档系统部署到各种平台。

🚀 GitHub Pages 部署

自动部署（推荐）

AutoDoc 已配置 GitHub Actions 自动部署：

推送代码到 GitHub：

git add .
git commit -m "更新文档"
git push origin main

自动触发部署：
- GitHub Actions 会自动检测 docs/ 目录的变更
- 自动构建 VuePress 文档
- 部署到 GitHub Pages
访问文档站点：
- 访问 https://your-username.github.io/autodoc/

手动部署

如果需要手动部署：

# 构建文档
npm run docs:build

# 部署到 GitHub Pages
npm run deploy:gh-pages

GitHub Pages 配置

进入仓库的 Settings 页面
找到 Pages 设置
选择 GitHub Actions 作为部署源

🌐 其他平台部署

Netlify 部署

连接 GitHub 仓库：
- 登录 Netlify
- 选择 "New site from Git"
- 连接您的 GitHub 仓库

配置构建设置：

Build command: npm run docs:build
Publish directory: docs/.vuepress/dist

环境变量（如果需要）：
```
NODE_VERSION=18
```

Vercel 部署

导入项目：
- 登录 Vercel
- 点击 "New Project"
- 导入 GitHub 仓库

配置设置：

{
  "buildCommand": "npm run docs:build",
  "outputDirectory": "docs/.vuepress/dist",
  "installCommand": "npm install"
}

自托管部署

使用 Docker

创建 Dockerfile：

FROM node:18-alpine

WORKDIR /app

# 复制 package 文件
COPY package*.json ./

# 安装依赖
RUN npm ci --only=production

# 复制源代码
COPY . .

# 构建文档
RUN npm run docs:build

# 使用 nginx 服务静态文件
FROM nginx:alpine
COPY --from=0 /app/docs/.vuepress/dist /usr/share/nginx/html

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

构建和运行：

# 构建镜像
docker build -t autodoc .

# 运行容器
docker run -p 8080:80 autodoc

使用 PM2

# 全局安装 PM2
npm install -g pm2

# 构建文档
npm run docs:build

# 使用 serve 提供静态文件服务
npm install -g serve

# 启动服务
pm2 start "serve docs/.vuepress/dist -p 3000" --name autodoc

🔧 部署配置

基础路径配置

如果部署到子路径，需要配置 base：

// docs/.vuepress/config.js
export default defineUserConfig({
  base: '/autodoc/', // 如果部署到 /autodoc/ 路径
  // 其他配置...
})

环境变量

在部署平台设置环境变量：

NODE_ENV=production
BASE_URL=https://your-domain.com

自定义域名

GitHub Pages 自定义域名

在 docs/.vuepress/public/ 目录下创建 CNAME 文件：
```
docs.yourdomain.com
```
在域名提供商处配置 DNS：
```
CNAME docs your-username.github.io
```

Netlify 自定义域名

在 Netlify 控制台中添加自定义域名
配置 DNS 记录指向 Netlify

📊 性能优化

构建优化

// docs/.vuepress/config.js
export default defineUserConfig({
  bundler: '@vuepress/bundler-vite',
  bundlerConfig: {
    viteOptions: {
      build: {
        rollupOptions: {
          output: {
            manualChunks: {
              vendor: ['vue', 'vue-router'],
              theme: ['@vuepress/theme-default']
            }
          }
        }
      }
    }
  }
})

CDN 配置

使用 CDN 加速静态资源：

export default defineUserConfig({
  head: [
    ['link', { rel: 'dns-prefetch', href: 'https://cdn.jsdelivr.net' }],
    ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }]
  ]
})

缓存策略

配置适当的缓存头：

# nginx 配置示例
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

location ~* \.(html)$ {
    expires 1h;
    add_header Cache-Control "public";
}

🔍 监控和分析

Google Analytics

// docs/.vuepress/config.js
import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics'

export default defineUserConfig({
  plugins: [
    googleAnalyticsPlugin({
      id: 'GA_MEASUREMENT_ID'
    })
  ]
})

错误监控

// 添加错误监控
export default defineUserConfig({
  head: [
    ['script', {
      src: 'https://browser.sentry-cdn.com/7.x.x/bundle.min.js'
    }]
  ]
})

🛠 故障排除

常见问题

构建失败：

# 清除缓存重新构建
rm -rf docs/.vuepress/.cache
rm -rf docs/.vuepress/.temp
npm run docs:build

路径问题：
- 检查 base 配置是否正确
- 确认所有链接使用相对路径
样式丢失：
- 检查静态资源路径
- 确认 CDN 配置正确

调试技巧

本地预览：
```
npm run docs:build
npm run docs:serve
```
检查构建输出：
```
ls -la docs/.vuepress/dist/
```
查看构建日志：
- 在 CI/CD 平台查看详细的构建日志
- 检查是否有警告或错误信息

📋 部署检查清单

部署前请确认：

[ ] 所有链接都是相对路径
[ ] 图片和静态资源路径正确
[ ] base 配置符合部署路径
[ ] 构建命令和输出目录配置正确
[ ] 环境变量设置完整
[ ] DNS 配置正确（如使用自定义域名）
[ ] HTTPS 证书配置（如需要）