居然配置一个pages配置了一两个小时，简直是要没耐心了，但是还是耐着性子部署成功了。

background： react + vite + ts 项目

1. gh-pages分支配置，但是注意package.json还要vite.config.ts的配置。

不知道哪里出了问题，缓存有误。dist删了又新建删了又新建反反复复...本来打算用deploy脚本。最后也是，只不过最后是手动配置的。

2.github action 配置。

这里面的env什么都不会写，靠ai来写build的yml完全不靠谱。还是要自己学会看懂。

Quickstart for GitHub Pages - GitHub Docs

关键时候还是要看文档，看报错。

心累心累，最后手动部署不知道怎么就那么顺利过了，主要是没有依赖gh-pages包？...还是问问聪明的ai，把这里不会的知识补一补吧！

一、核心认知纠正（先厘清关键误区）

1. 「不用 gh-pages 包也能部署」是对的：gh-pages 包只是简化了「把 dist 文件推到 gh-pages 分支」的操作，本质是手动也能完成（复制 dist 文件到 gh-pages 分支、提交推送），所以你手动部署成功完全合理；
2. AI 生成的 GitHub Action YML 不靠谱的核心原因：AI 容易忽略项目技术栈（Vite+TS）的构建细节、环境变量、路径配置，必须结合官方文档定制；
3. 缓存 / 反复删 dist 的问题：大概率是「路径配置错误」或「构建命令未清空旧产物」，而非单纯删文件能解决。

二、React+Vite+TS 部署 GitHub Pages 核心配置（手动 / 自动两种方式）

前提准备

1. GitHub 仓库设置：仓库→Settings→Pages→Build and deployment→Source 选择「Deploy from a branch」，Branch 选择「gh-pages」+「/(root)」，保存；
2. 本地项目确认：package.json 中补充 homepage（关键！路径错了页面会空白）：

   // 注意：如果是「用户名.github.io/仓库名」的形式，必须写仓库名；如果是自定义域名/根域名，写域名
   "homepage": "https://你的用户名.github.io/你的仓库名/", 
   

方式 1：手动部署（你成功的方式，梳理逻辑）

手动部署的核心是「把 Vite 构建后的 dist 文件夹内容，推到 gh-pages 分支的根目录」，步骤：

1. 本地构建（确保 dist 是最新的）：

   # 先清空旧dist（避免缓存），再构建
   rm -rf dist && vite build
   

2. 切换到 gh-pages 分支（如果没有则新建）：

   git checkout -b gh-pages # 新建并切换
   # 或已有分支：git checkout gh-pages
   

3. 删除 gh-pages 分支下除了 dist 的无关文件（保留.gitignore 等必要文件），把 dist 里的所有文件复制到 gh-pages 分支根目录；
4. 提交并推送：

   git add .
   git commit -m "deploy: gh-pages"
   git push origin gh-pages
   

5. 等待 1-2 分钟，刷新 GitHub Pages 地址即可。

方式 2：vite.config.ts 关键配置（解决路径 / 空白问题）

Vite 的配置直接影响构建产物的路径，是最容易踩坑的地方：

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  // 核心：base路径必须和homepage一致！
  base: '/你的仓库名/', // 比如仓库名是react-vite-ts-demo，就写/base: '/react-vite-ts-demo/'
  build: {
    outDir: 'dist', // 输出目录，默认就是dist，可省略
    emptyOutDir: true, // 构建前自动清空dist（不用手动删！）
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'), // 如有别名，确保配置正确
    },
  },
});

方式 3：GitHub Action 自动部署（正确的 YML 配置）

不用依赖 AI，直接用这个模板，替换注释里的内容即可（保存到 .github/workflows/deploy.yml）：

name: Deploy to GitHub Pages

on:
  # 当推送到main/master分支时触发（看你的主分支名）
  push:
    branches: [main]
  # 也可以手动触发
  workflow_dispatch:

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      # 1. 拉取代码
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      # 2. 安装Node.js（指定版本，比如18/20，和本地一致）
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm' # 缓存npm依赖，加速构建

      # 3. 安装依赖
      - name: Install dependencies
        run: npm install

      # 4. 构建项目
      - name: Build project
        run: npm run build # 对应package.json里的build命令（vite build）

      # 5. 部署到gh-pages分支
      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          # 部署的文件夹（Vite构建后的dist）
          folder: dist
          # 部署到的分支
          branch: gh-pages
          # 提交信息
          commit-message: 'Deploy: Build from main branch'

三、常见踩坑点（你遇到的问题对应）

1. 页面空白 / 资源 404：
   • 原因：vite.config.ts 的 base 路径和 package.json 的 homepage 不一致；
   • 解决：两者必须匹配，比如 homepage 是 https://xxx.github.io/xxx/，base 就必须是 /xxx/。
2. dist 删了又建还是有问题：
   • 原因：没开 emptyOutDir: true，构建时旧文件没清干净；
   • 解决：在 vite.config.ts 里加上 emptyOutDir: true，构建前自动清空。
3. GitHub Action 构建失败：
   • 常见原因：Node 版本不匹配、依赖安装失败、构建命令错误；
   • 解决：Action 里指定和本地一致的 Node 版本，检查 npm run build 是否能在本地正常执行。
4. 不用 gh-pages 包也能部署：
   • 原理：gh-pages 包的核心代码就是「切换分支→复制 dist→提交推送」，手动做这些步骤完全等价，只是包简化了操作。

四、后续学习重点（针对性提升）

1. Vite 构建配置：重点学 base、build 相关配置（官方文档：https://vitejs.dev/config/build-options.html），理解构建产物的路径逻辑；
2. GitHub Pages 路径规则：
   • 根域名（xxx.github.io）：base 写 /，homepage 写 https://xxx.github.io/；
   • 仓库域名（xxx.github.io/ 仓库名）：base 必须写 /仓库名/，否则资源路径错误；
3. GitHub Action 基础：
   • 先看官方文档：https://docs.github.com/en/actions/quickstart；
   • 重点理解 on（触发条件）、jobs（任务）、steps（步骤）、uses（复用别人的 Action）；
4. 调试技巧：
   • 部署后看 GitHub Pages 的构建日志（仓库→Settings→Pages→Build and deployment→Recent deployments）；
   • 本地构建后，用 npx serve dist 预览，先确保本地能正常访问，再部署。

总结一下：你手动部署成功的核心是绕开了「配置错误」或「工具依赖」的坑，本质是路径和构建产物的正确性。后续只要把 vite.config.ts 的 base、package.json 的 homepage 配置对，不管手动还是 Action 都能稳过。