Skip to content

# 静态文档部署指南 ​

本文档说明如何将 DPS Plugins 组件库的用户手册以静态资源的形式发布给用户。

## 快速开始 ​

### 1. 构建文档 ​

bash

    npm run docs:build  # 构建文档
    npm run build       # 构建组件库

### 2. 本地预览 ​

bash

    # 使用 VitePress 预览（推荐）
    npm run docs:preview

    # 使用静态服务器预览
    npx serve -l 5500 docs/.vitepress/dist -s

## 部署选项 ​

### 选项 1: 作为 npm 包的一部分 ​

文档会作为静态资源包含在 npm 包中：

bash

    npm publish

用户安装包后，可以在 `node_modules/ysj_plugins_dps/docs/` 目录找到文档。

### 选项 2: 独立静态网站 ​

将 `dist/docs` 目录部署到任何静态网站托管服务：

- GitHub Pages: 上传到 `gh-pages` 分支
- Netlify: 直接拖拽 `dist/docs` 目录
- Vercel: 连接 GitHub 仓库，设置构建目录为 `dist/docs`
- 阿里云 OSS/腾讯云 COS: 上传 `dist/docs` 目录内容

### 选项 3: 企业内部部署 ​

将 `dist/docs` 目录部署到内部 Web 服务器：

bash

    # 复制到 Web 服务器目录
    cp -r dist/docs/* /var/www/html/docs/

    # 或使用 nginx 配置
    server {
        listen 80;
        server_name your-domain.com;
        root /path/to/dist/docs;
        index index.html;

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

## 目录结构 ​

构建后的文档结构：

    dist/
    ├── docs/                    # 静态文档目录
    │   ├── index.html          # 首页
    │   ├── components/         # 组件文档
    │   ├── functions/          # 函数文档
    │   ├── assets/             # 静态资源
    │   └── deploy-info.json    # 部署信息
    ├── src/                    # 组件库源码
    └── style.css              # 样式文件

## 访问路径 ​

- 本地开发: `http://localhost:4174/`
- 静态部署: `https://your-domain.com/docs/`
- npm 包内: `node_modules/ysj_plugins_dps/docs/`

## 自定义配置 ​

### 修改基础路径 ​

编辑 `docs/.vitepress/config.js`:

javascript

    export default defineConfig({
      base: '/your-custom-path/', // 修改为你的路径
      outDir: '../dist/docs',
      // ...
    })

### 添加自定义域名 ​

javascript

    export default defineConfig({
      base: '/',
      outDir: '../dist/docs',
      // 添加域名配置
      head: [
        ['link', { rel: 'canonical', href: 'https://your-domain.com/' }]
      ],
      // ...
    })

## 自动化部署 ​

### GitHub Actions 示例 ​

创建 `.github/workflows/deploy-docs.yml`:

yaml

    name: Deploy Docs

    on:
      push:
        branches: [ main ]
        paths: [ 'docs/**' ]

    jobs:
      deploy:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v3
          - uses: actions/setup-node@v3
            with:
              node-version: '16'
          - run: npm ci
          - run: npm run docs:deploy
          - name: Deploy to GitHub Pages
            uses: peaceiris/actions-gh-pages@v3
            with:
              github_token: ${{ secrets.GITHUB_TOKEN }}
              publish_dir: ./dist/docs

## 故障排除 ​

### 常见问题 ​

1. 路径问题: 确保 `base` 配置与实际部署路径匹配
2. 资源加载失败: 检查相对路径是否正确
3. 404 错误: 配置服务器支持 SPA 路由

### 调试命令 ​

bash

    # 检查构建输出
    ls -la dist/docs/

    # 验证 HTML 文件
    cat dist/docs/index.html

    # 检查资源路径
    grep -r "href=" dist/docs/ | head -10

## 更新文档 ​

每次更新文档后，重新运行构建命令：

bash

    npm run docs:deploy

文档会自动更新到 `dist/docs` 目录，可以重新部署到服务器。