引言

本文是一份详尽的技术指南，旨在帮助开发者为基于 Vite 和 React 的项目配置一套完整的 CI/CD（持续集成/持续部署）流程，实现代码提交后自动部署到 GitHub Pages。文章将覆盖从项目配置、工作流编写到常见问题排查的全过程，力求通俗易懂，可作为未来项目的标准参考。

第一步：配置 Vite 的 `base` 路径

▶ 为什么需要这一步？

GitHub Pages 通常会将你的项目部署到一个子目录下（例如 https://username.github.io/repo-name/）。如果不进行配置，Vite 打包出的静态资源（如 CSS 和 JS 文件）会默认从根目录 (/) 加载，这会导致所有资源加载失败，页面一片空白。

▶ 如何配置？

打开项目根目录下的 vite.config.ts 文件，添加 base 配置项。

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

// 你的仓库名称
const REPO_NAME = "xxxx";

// https://vite.dev/config/
export default defineConfig({
  // 👇 新增这个 base 配置
  base: `/${REPO_NAME}/`, 
  plugins: [react(), tailwindcss()],
});

第二步：配置 GitHub 仓库

▶ 为什么需要这一步？

你需要明确告知 GitHub，你的 Pages 站点的源文件将由 GitHub Actions 自动构建和提供，而不是来自于某个特定的分支（如 main 或 gh-pages）。

▶ 如何配置？

进入你的 GitHub 仓库，点击右上角的 **”Settings”**。
在左侧菜单中，找到 “Pages” 选项并点击。
在 “Build and deployment” 设置下，将 “Source” 从 "Deploy from a branch" 修改为 **"GitHub Actions"**。

第三步：创建 GitHub Action 工作流

▶ 这是做什么的？

这是整个自动化流程的核心。我们将创建一个 .yml 文件来定义 CI/CD 的所有步骤：何时触发、在什么环境中运行、以及具体执行哪些命令。

▶ 如何创建？

在项目根目录创建文件夹路径：.github/workflows/。
在该路径下创建一个新文件，命名为 deploy.yml。
将以下代码完整复制到 deploy.yml 文件中。

# 工作流名称
name: Deploy to GitHub Pages

# 触发条件：当代码被 push到 main 分支时触发
on:
  push:
    branches:
      - main # 注意：如果你的主分支不叫 main，请修改此处

# 权限配置：授予 Actions 读写 GitHub Pages 的权限
permissions:
  contents: read
  pages: write
  id-token: write

# 任务（Jobs）
jobs:
  # 构建任务
  build:
    runs-on: ubuntu-latest # 使用最新的 Ubuntu 虚拟机环境
    steps:
      # 步骤1：检出代码
      # 使用官方的 actions/checkout@v4 拉取你的仓库代码
      - name: Checkout
        uses: actions/checkout@v4

      # 步骤2：设置 Node.js 环境
      # 使用 actions/setup-node@v4 来安装指定版本的 Node.js
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20.x # 建议使用一个较新的长期支持（LTS）版本
          cache: 'npm' # 缓存 npm 依赖，加快后续构建速度

      # 步骤3：安装依赖
      # 使用 npm ci 而不是 npm install，它更快且能保证使用 lock 文件中的精确版本
      - name: Install dependencies
        run: npm ci

      # 步骤4：构建项目
      # 运行 package.json 中定义的 build 脚本
      - name: Build
        run: npm run build

      # 步骤5：上传构建产物
      # 将打包好的 dist 文件夹上传为一个名为 github-pages 的构件（artifact）
      # 后续的 deploy 任务会下载这个构件
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist # 指定要上传的文件夹路径

  # 部署任务
  deploy:
    needs: build # 依赖于 build 任务，必须在 build 成功后才运行
    runs-on: ubuntu-latest
    environment:
      name: github-pages # 指定部署环境为 github-pages
      url: ${{ steps.deployment.outputs.page_url }} # 将部署后的 URL 输出为变量
    steps:
      # 步骤1：部署到 GitHub Pages
      # 使用官方的 actions/deploy-pages@v4 来执行部署
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

将此文件提交并推送到你的 main 分支，自动化流程便会首次启动。

第四步：配置仓库首页About

找到编辑按钮 在你的仓库主页右侧，找到你截图中的 “About” 部分。注意看 “About” 标题旁边有一个**小齿轮图标 (⚙️)**，点击它。
填写信息 点击齿轮后，会弹出一个编辑框，里面有几个输入栏：
- Description (描述): 建议在这里写上一句简短的话来描述你的项目，例如：“一个基于 React 和 TypeScript 构建的低代码编辑器。” 这会让你的项目看起来更专业。
- Website (网站): 这就是你要找的地方！ 在这个输入框里，填上你完整的 GitHub Pages 链接。链接的格式是：
  1
  https://<你的GitHub用户名>.github.io/<你的仓库名>/
  请务必把 <你的GitHub用户名> 和 <你的仓库名> 替换成你自己的信息。例如：https://xxmudcloudxx.github.io/xxxx/
- Topics (主题/标签): 你还可以在这里为你的项目打上标签，比如 react, typescript, low-code, vite, zustand 等。这能让其他人在搜索时更容易发现你的项目。
保存更改 填写完毕后，点击绿色的 “Save changes” 按钮

最终结果

![image-20250614025210561](自动化部署到 GitHub Pages 全流程详解/image-20250614025210561.png)

常见问题与最佳实践

问题：工作流报错 `Dependencies lock file is not found`

▶ 根源分析

此错误是因为工作流中的 npm ci 命令强依赖 package-lock.json 文件来保证依赖版本的一致性，但这个文件并未提交到你的代码仓库中。最常见的原因是本地开发时使用了 cnpm 或其他不生成标准锁文件的包管理器。

▶ 解决方案与最佳实践

标准化依赖管理：一个项目应该有且仅有一个权威的锁文件。我们推荐以 npm 和 package-lock.json 作为标准。
删除node_modules文件夹：可以用下面的命令(这个是递归删掉当前文件夹及其子文件夹所有node_modules文件夹的，偷个懒直接拿过来用了)
1. ```
Get-ChildItem -Path . -Recurse -Directory -Filter "node_modules" | ForEach-Object { rimraf $_.FullName }
```
生成锁文件：在本地项目根目录删除掉node_modules文件夹后再明确地运行一次 npm install。此命令会自动生成或更新 package-lock.json 文件。
提交锁文件：务必将 package-lock.json 文件提交到你的 Git 仓库。它是项目的重要组成部分，而非临时文件。
**CI/CD 中的 npm ci**：坚持在自动化流程中使用 npm ci 是最佳实践。它比 npm install 更快、更安全，因为它会进行纯净安装并确保版本与锁文件完全一致。

总结

至此，一个专业、可靠的前端自动化部署流水线就搭建完成了。回顾一下核心要点：

Vite base 配置：确保资源路径在 GitHub Pages 子目录下正确无误。
GitHub Pages 部署源：必须设置为 “GitHub Actions”。
依赖锁文件：必须将 package-lock.json 提交到仓库，以配合 npm ci 的工作。

遵循以上步骤，你未来的任何 Vite 项目都可以快速、规范地实现自动化部署。