---
name: "vite-github-pages-deploy"
description: "Vite项目GitHub Pages自动部署 - 修复跨平台依赖问题，配置CI/CD"
slug: "vite-github-pages-deploy"
displayName: "Vite GitHub Pages 部署"
version: "1.0.0"
---

# Vite + GitHub Pages 自动部署 Skill

## 用途
将 Vite 构建的前端项目部署到 GitHub Pages，自动处理 Windows/Linux 跨平台依赖问题。

## 适用场景
- Vite 构建的静态网站
- 需要从本地 Windows 开发环境部署到 GitHub Pages
- 遇到 rollup 跨平台原生绑定问题

## 前置条件
- 项目使用 Vite 构建
- 有 GitHub 账号
- 本地已安装 Node.js 和 Git

## 使用步骤

### 1. 初始化 Git 仓库
```bash
cd 你的项目目录
git init
git add .
git commit -m "Initial commit"
```

### 2. 创建 GitHub 仓库
- 在 GitHub 创建新仓库（公开或私有）
- 添加 remote：
```bash
git remote add origin https://github.com/用户名/仓库名.git
```

### 3. 配置 GitHub Actions

创建 `.github/workflows/deploy.yml`：

```yaml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

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

concurrency:
  group: pages-deploy
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies
        # 关键：删除 package-lock.json 避免跨平台问题
        run: rm -f package-lock.json && npm install

      - name: Build
        run: npm run build

      - name: Configure Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist/

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

### 4. 配置 GitHub Pages

1. 打开 `https://github.com/用户名/仓库名/settings/pages`
2. **Build and deployment** → **Source** 选择 **GitHub Actions**
3. 点击 **Save**

### 5. 推送并部署

```bash
git add .
git commit -m "ci: add GitHub Pages deployment"
git push origin main
```

等待 GitHub Actions 运行完成，访问 `https://用户名.github.io/仓库名/`

## 常见问题

### Q: 报错 Cannot find module '@rollup/rollup-linux-x64-gnu'
**A**: 已在本 Skill 中解决，通过 `rm -f package-lock.json && npm install` 让 GitHub Actions 重新生成平台特定的依赖。

### Q: 仓库私有时 Pages 无法使用
**A**: GitHub Pages 对私有仓库需要付费。解决方案：
- 将仓库设为 Public（免费永久）
- 或使用 Vercel/Netlify（支持私有仓库免费部署）

### Q: 修改后网站没有更新
**A**: 
1. 等待 1-2 分钟（部署需要时间）
2. 按 `Ctrl+F5` 强制刷新浏览器
3. 检查 GitHub Actions 是否成功（绿色对勾）

## 后续更新流程

```bash
# 1. 本地修改代码
# 2. 提交并推送
git add .
git commit -m "描述修改内容"
git push origin main

# 3. 自动部署，1-2 分钟后生效
```

## 相关链接
- [GitHub Pages 文档](https://docs.github.com/pages)
- [Vite 部署指南](https://vitejs.dev/guide/static-deploy.html)