如何借助Github pages部署React+vite静态前端项目

这里只针对静态页面啊，需要向后端服务器访问数据的不行，所以还是有点受限了。

在部署时遇到了许多问题，所以想和大家分享一下我的解决方案。

我自己也去找了许多教程，下面贴出一些个人觉得有帮助的：

来认真学一下，项目部署到 github pages-腾讯云开发者社区-腾讯云

在 GitHub Pages 上部署 React 应用|极客教程

【‌轻松上手：React Vite 应用快速部署至 Github Pages】www.bilibili.com/video/BV1ch...

【免费部署一个静态网站！在GitHub上部署静态网站教程】www.bilibili.com/video/BV1D2...

虽然啊，这些都没有解决我的问题，但是讲的还是不错的。其中有些是使用git命令推到Github的仓库上，但是不知道为什么输命令的话连不上github

报错如下：

fatal: unable to access 'https://github.com/仓库名/项目名.git/': Failed to connect to github.com port 443 after 21143 ms: Couldn't connect to server

遇到过404的问题即访问不到资源，也遇到过不报错但全白屏的情况。其实都是路径不对的原因，接下来进行分析。

GitHub Pages 的两种部署方式

1. 用户/组织站点

   • 仓库名：username.github.io
   • 访问地址：https://username.github.io/
   • 部署在根路径，base 配置为 /

2. 项目站点

   • 仓库名：任意名称（如 myWeb）
   • 访问地址：https://username.github.io/myWeb/
   • 部署在子路径，需要特殊配置

关键配置项

• base：Vite 配置，控制静态资源（JS/CSS/图片）的引用路径
• basename：React Router 配置，控制路由的基础路径

失败原因分析

问题 1：文件结构错误

现象： 404 错误，资源找不到

原因： 上传时把 dist 文件夹本身拖到 GitHub，导致结构变成：

仓库根目录/
  └── dist/
      ├── index.html
      └── assets/

实际访问路径变成 https://xxx.github.io/myWeb/index.html，而 HTML 里的资源路径是 /myWeb/assets/...，路径不匹配。

解决方案：

• 进入 dist 文件夹内部
• 全选里面的文件和文件夹（不选 dist 本身）
• 拖到 GitHub 仓库根目录

正确结构：

仓库根目录/
  ├── index.html
  ├── assets/
  └── vite.svg

问题 2：base 配置错误

现象： 资源 404，或者图标能显示但 JS/CSS 加载失败

原因： base 配置不正确导致资源路径错误

尝试过的配置：

1. base: '/' （默认）

   <script src="/assets/index.js"></script>

   实际访问：https://xxx.github.io/assets/index.js ❌

   正确路径：https://xxx.github.io/myWeb/assets/index.js

2. base: '/visual-editor/' （绝对路径）

   <script src="/myWeb/assets/index.js"></script>

   生产环境：✅ 正确

   本地开发：❌ npm run dev 和 npm run preview 都会失败

3. base: './' （相对路径）

   <script src="./assets/index.js"></script>

   看似完美，但遇到了问题 3...

问题 3：React Router 路由匹配失败

现象：

• 资源加载成功（304 /200 状态码）
• 控制台无报错
• 页面白屏
• DOM 中只有 <div id="root"><div id="app"></div></div>，app 内部为空

原因： BrowserRouter 在子路径下路由匹配失败

技术细节：

• GitHub Pages 访问地址：https://xxx.github.io/myWeb/
• BrowserRouter 默认 basename 是 /
• 当前实际路径是 /myWeb/
• 路由配置的 path="/" 匹配不上实际路径 /myWeb/
• React 渲染了 <div id="app"> 但 Routes 内没有匹配的组件

为什么本地 preview 也白屏？

• npm run preview 运行在 http://localhost:4173/
• 如果 base 是 /myWeb/，资源路径变成 http://localhost:4173/myWeb/assets/...
• 但实际文件在 http://localhost:4173/assets/...
• 路径不匹配导致加载失败或路由失败

问题 4：开发/生产环境冲突

矛盾点：

• 开发环境（npm run dev）需要 base 为 /
• 生产环境（GitHub Pages）需要 base 为 /myWeb/
• 写死任何一个值都会导致另一个环境失败

最终解决方案

1. 动态配置 base（vite.config.ts）

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

export default defineConfig(({ mode }) => ({
  plugins: [react()],
  resolve: {
    alias: {
      '@': '/src',
    },
  },
  server: {
    port: 3000,
  },
  base: mode === 'production' ? '/myWeb/' : '/',
}));

原理：

• mode 参数由 Vite 自动传入
• npm run dev：mode = 'development'，base = '/'
• npm run build：mode = 'production'，base = '/visual-editor/'

2. 动态配置 basename（src/main.tsx）

import React from 'react';
import ReactDOM from 'react-dom/client';
import { BrowserRouter } from 'react-router-dom';
import App from './App';
import './styles/base.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <BrowserRouter basename={import.meta.env.BASE_URL}>
      <App />
    </BrowserRouter>
  </React.StrictMode>
);

原理：

• import.meta.env.BASE_URL 是 Vite 内置环境变量
• 自动读取 vite.config.ts 中的 base 值
• 开发环境：basename = '/'
• 生产环境：basename = '/myWeb/'

3. 部署流程

1. 构建项目
npm run build

2. 上传文件
打开本地 dist 文件夹
全选里面的所有内容（index.html、assets 文件夹等）
拖到 GitHub 仓库根目录上传

3. 配置 GitHub Pages
仓库 Settings → Pages
Source: Deploy from a branch
Branch: main
Folder: / (root)
Save

4. 等待 1-2 分钟后访问
https://username.github.io/myWeb/

常见问题排查

白屏无报错

1. 检查 DOM 结构，看 <div id="root"> 里有没有内容
2. 如果只有空的 <div id="app">，是路由问题
3. 确认 BrowserRouter 的 basename 配置

资源 404

1. F12 → Network 面板查看失败的资源路径
2. 对比实际文件在 GitHub 上的位置
3. 检查 vite.config.ts 的 base 配置

缓存问题

1. 强制刷新：Ctrl + Shift + R（Windows）
2. 无痕模式访问
3. 清除浏览器缓存
4. URL 加随机参数：?v=123（没试过有没有用）

本地预览失败

npm run preview

如果白屏，说明配置有问题，不要急着部署，先在本地解决。

总结

部署 Vite + React Router 到 GitHub Pages 的核心是：

1. 理解路径差异：开发环境根路径 vs 生产环境子路径
2. 两处配置：静态资源路径（base）+ 路由基础路径（basename）
3. 环境区分：使用 Vite 的 mode 参数动态配置
4. 正确上传：上传 dist 内容，不是 dist 文件夹

配置正确后，开发和部署都能正常工作，无需手动切换配置。

如果网络上实在找不到解决方法，可以去问ai的，现在大模型越来越强，将问题和目标清楚地描述给ai，大概率可以解决问题。