系统覆写 // SYSTEM OVERRIDE

Appearance

Deployment Guide ​

Learn how to deploy your VitePress documentation site to various platforms.

Building for Production ​

Build your site for production:

bash
npm run docs:build

This generates static files in docs/.vitepress/dist/.

Deployment Platforms ​

GitHub Pages ​

  1. Create a .github/workflows/deploy.yml file:
yaml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run docs:build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/.vitepress/dist
  1. Configure the base URL in site.config.js:
javascript
site: {
  base: "/your-repo-name/",
}

GitLab Pages ​

This template includes a .gitlab-ci.yml file for GitLab Pages deployment.

Update the base in site.config.js if needed:

javascript
site: {
  base: "/your-project-name/",
}

The CI/CD pipeline will automatically deploy on push to the main branch.

Netlify ​

  1. Connect your repository to Netlify
  2. Configure build settings:
    • Build command: npm run docs:build
    • Publish directory: docs/.vitepress/dist

Vercel ​

  1. Import your repository to Vercel
  2. Configure build settings:
    • Build command: npm run docs:build
    • Output directory: docs/.vitepress/dist

Custom Server ​

After building, upload the contents of docs/.vitepress/dist/ to your web server.

Configure your web server to:

  • Serve index.html for directory requests
  • Handle 404s by serving the custom 404 page
  • Enable gzip compression for better performance

Base URL Configuration ​

If deploying to a subdirectory, update the base in site.config.js:

javascript
site: {
  base: "/subdirectory/",
}

This ensures all links and assets work correctly.

Environment-Specific Configuration ​

You can use environment variables for different deployment environments:

javascript
export default {
  site: {
    base: process.env.BASE_URL || "/",
  },
}

Then set the environment variable during build:

bash
BASE_URL=/my-docs/ npm run docs:build

Troubleshooting ​

  • Ensure base is set correctly in site.config.js
  • Check that all internal links are relative or use the correct base path

Assets Not Loading ​

  • Verify assets are in the docs/public/ directory
  • Check that asset paths in markdown are correct
  • Ensure the build process includes all necessary files

404 Errors ​

  • Configure your hosting platform to handle SPAs correctly
  • Ensure the 404 page is properly configured in VitePress