Vite + GitHub Pages 自动部署 Skill
用途
将 Vite 构建的前端项目部署到 GitHub Pages，自动处理 Windows/Linux 跨平台依赖问题。
适用场景
- Vite 构建的静态网站
- 需要从本地 Windows 开发环境部署到 GitHub Pages
- 遇到 rollup 跨平台原生绑定问题
前置条件
- 项目使用 Vite 构建
- 有 GitHub 账号
- 本地已安装 Node.js 和 Git
使用步骤
1. 初始化 Git 仓库
cd 你的项目目录
git init
git add .
git commit -m "Initial commit"
2. 创建 GitHub 仓库
- 在 GitHub 创建新仓库（公开或私有）
- 添加 remote：
git remote add origin https://github.com/用户名/仓库名.git
3. 配置 GitHub Actions
创建 .github/workflows/deploy.yml：
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
- 打开
https://github.com/用户名/仓库名/settings/pages - Build and deployment → Source 选择 GitHub Actions
- 点击 Save
5. 推送并部署
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 是否成功（绿色对勾）
后续更新流程
# 1. 本地修改代码
# 2. 提交并推送
git add .
git commit -m "描述修改内容"
git push origin main
# 3. 自动部署，1-2 分钟后生效
相关链接
- GitHub Pages 文档
- Vite 部署指南
