部署指南

将ECharts知识库部署到生产环境的完整指南

---

📋 部署前检查清单

• [ ] 所有文档链接正常
• [ ] 图片资源已添加到 docs/public/
• [ ] 搜索功能测试通过
• [ ] 深色/浅色模式切换正常
• [ ] 移动端响应式测试通过
• [ ] SEO元数据配置正确
• [ ] 自定义域名配置(如需要)

---

🌐 部署选项

选项1: GitHub Pages (推荐)

优点: 免费、简单、自动HTTPS
适合: 开源项目、个人博客

步骤1: 配置基础路径

编辑 .vitepress/config.ts:

export default defineConfig({
  base: '/echarts-kb/',  // 仓库名
  // ...其他配置
})

步骤2: 创建部署脚本

.github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm
      
      - name: Setup Pages
        uses: actions/configure-pages@v4
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build with VitePress
        run: npm run docs:build
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

步骤3: 启用GitHub Pages

1. 进入仓库 Settings → Pages
2. Source 选择 "GitHub Actions"
3. 保存后会自动部署

访问: https://yourusername.github.io/echarts-kb/

---

选项2: Vercel

优点: 零配置、全球CDN、自动HTTPS
适合: 商业项目、需要高性能

步骤1: 连接GitHub

1. 访问 https://vercel.com
2. 点击 "New Project"
3. 导入GitHub仓库

步骤2: 配置构建设置

Framework Preset: VitePress
Build Command: npm run docs:build
Output Directory: docs/.vitepress/dist
Install Command: npm install

步骤3: 部署

点击 "Deploy",Vercel会自动构建并发布

访问: https://echarts-kb.vercel.app

---

选项3: Netlify

优点: 强大的表单处理、A/B测试
适合: 需要后端集成的项目

步骤1: 创建netlify.toml

[build]
  publish = "docs/.vitepress/dist"
  command = "npm run docs:build"

[build.environment]
  NODE_VERSION = "18"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

步骤2: 连接到Netlify

1. 访问 https://netlify.com
2. 拖拽项目文件夹或连接GitHub
3. 自动检测配置并部署

---

选项4: 自建服务器 (Nginx)

优点: 完全控制、内网部署
适合: 企业内部、私有化部署

步骤1: 构建静态文件

npm run docs:build

步骤2: 配置Nginx

server {
    listen 80;
    server_name echarts-kb.example.com;
    root /var/www/echarts-kb;
    index index.html;

    # Gzip压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

    # 缓存静态资源
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # SPA路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 安全头
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
    add_header X-XSS-Protection "1; mode=block";
}

步骤3: 上传文件

scp -r docs/.vitepress/dist/* user@server:/var/www/echarts-kb/

步骤4: 配置HTTPS (Let's Encrypt)

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d echarts-kb.example.com

---

🔧 高级配置

自定义域名

GitHub Pages

1. 在仓库根目录创建 CNAME 文件:

docs.echarts.com

2. 在DNS提供商处添加CNAME记录:

CNAME docs.echarts.com yourusername.github.io

Vercel/Netlify

在控制面板直接添加自定义域名,会自动配置DNS

---

PWA支持

编辑 .vitepress/config.ts:

export default defineConfig({
  head: [
    ['link', { rel: 'manifest', href: '/manifest.json' }],
    ['meta', { name: 'theme-color', content: '#667eea' }],
  ],
})

创建 docs/public/manifest.json:

{
  "name": "ECharts 技术知识库",
  "short_name": "ECharts KB",
  "description": "系统化、结构化、源码级深度的ECharts完全指南",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#667eea",
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

---

分析统计

Google Analytics

编辑 .vitepress/config.ts:

export default defineConfig({
  head: [
    ['script', { async: true, src: 'https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID' }],
    ['script', {}, `
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'GA_MEASUREMENT_ID');
    `]
  ]
})

Umami (隐私友好)

head: [
  ['script', { 
    defer: true, 
    src: 'https://umami.example.com/script.js',
    'data-website-id': 'YOUR_WEBSITE_ID'
  }]
]

---

🚀 性能优化

1. 图片优化

# 安装imagemin
npm install -g imagemin-cli imagemin-mozjpeg imagemin-pngquant

# 压缩图片
imagemin docs/public/*.png --out-dir=docs/public/optimized/

2. 预加载关键资源

<!-- 在head中添加 -->
<link rel="preload" href="/assets/main.js" as="script">
<link rel="preload" href="/assets/main.css" as="style">

3. CDN加速

使用Cloudflare等CDN服务:

1. 注册Cloudflare账号
2. 添加网站域名
3. 修改DNS nameservers
4. 自动获得全球CDN加速

---

🔍 SEO优化

Sitemap生成

安装插件:

npm install vitepress-plugin-sitemap

配置 .vitepress/config.ts:

import { sitemap } from 'vitepress-plugin-sitemap'

export default defineConfig({
  sitemap: {
    hostname: 'https://echarts-kb.example.com',
    lastmod: new Date().toISOString(),
  }
})

robots.txt

创建 docs/public/robots.txt:

User-agent: *
Allow: /

Sitemap: https://echarts-kb.example.com/sitemap.xml

---

🛡️ 安全加固

内容安全策略(CSP)

Nginx配置:

add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline';";

HTTPS强制跳转

server {
    listen 80;
    server_name echarts-kb.example.com;
    return 301 https://$server_name$request_uri;
}

---

📊 监控与告警

Uptime监控

使用UptimeRobot(免费):

1. 注册 https://uptimerobot.com
2. 添加监控URL
3. 设置检查间隔(5分钟)
4. 配置告警通知(邮件/短信)

错误追踪

集成Sentry:

npm install @sentry/browser

import * as Sentry from '@sentry/browser'

Sentry.init({
  dsn: 'YOUR_SENTRY_DSN',
  environment: 'production'
})

---

🔄 持续集成/持续部署(CI/CD)

GitHub Actions完整示例

.github/workflows/ci-cd.yml:

name: CI/CD Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      
      - name: Install dependencies
        run: npm ci
      
      - name: Lint check
        run: npm run lint
      
      - name: Build test
        run: npm run docs:build

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run docs:build
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/.vitepress/dist
          commit_message: 'deploy: ${{ github.event.head_commit.message }}'

---

🎯 部署检查清单

部署前逐项检查:

功能性检查

• [ ] 所有页面可以正常访问
• [ ] 内部链接无404错误
• [ ] 搜索功能正常工作
• [ ] 深色/浅色模式切换正常
• [ ] 移动端导航菜单可用
• [ ] 代码复制按钮有效

性能检查

• [ ] 首屏加载时间 < 2秒
• [ ] Lighthouse评分 > 90
• [ ] 图片已压缩优化
• [ ] Gzip/Brotli压缩启用
• [ ] 浏览器缓存配置正确

SEO检查

• [ ] 每个页面有唯一的title
• [ ] meta description配置
• [ ] Open Graph标签完整
• [ ] sitemap.xml可访问
• [ ] robots.txt配置正确

安全检查

• [ ] HTTPS证书有效
• [ ] 安全头配置正确
• [ ] 无敏感信息泄露
• [ ] CORS策略合理

---

🆘 常见问题

Q1: 部署后页面空白?

原因: 基础路径配置错误

解决:

// .vitepress/config.ts
base: '/repository-name/'  // 确保与仓库名一致

Q2: 刷新页面404?

原因: SPA路由需要fallback配置

解决(Nginx):

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

Q3: 搜索不工作?

原因: 本地搜索索引未正确构建

解决:

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

Q4: 图片加载失败?

原因: 图片路径错误

解决:

• 图片放在 docs/public/ 目录
• 引用时使用绝对路径: /image.png

---

📞 获取帮助

• 📖 VitePress官方文档
• 💬 GitHub Discussions
• 🐛 Issue Tracker

---

祝您部署顺利!🚀