在 GitHub Pages 上部署 Vite/React 应用程序是一个令人兴奋的里程碑，但这个过程有时会带来意想不到的挑战，特别是在处理图像和资产时。这篇博文将引导您完成整个过程，从最初的部署到解决常见问题并找到有效的解决方案。

无论您是初学者还是有经验的人，本指南都将帮助您避免常见的陷阱，并成功部署您的 Vite/React 应用程序，并正确渲染所有资源。

先决条件

在我们深入之前，请确保您具备以下条件：

• Vite/React 项目：本指南假设您已使用 Vite 作为构建工具并使用 React 作为框架来设置项目。
• GitHub 存储库：您应该有一个现有的 GitHub 存储库，您可以在其中推送应用程序进行部署。
• 已启用 GitHub Pages：确保在用于部署的存储库设置中启用 GitHub Pages。

第 1 步：初始化项目和 GitHub Pages 部署

首先，确保您的 Vite/React 应用程序已正确初始化并在本地主机上运行。您可以按照如下方式创建一个基础的Vite项目：

npm create vite@latest

安装依赖项：

npm install

在本地运行项目以确认一切正常：

npm run dev

项目准备就绪后，将其推送到 GitHub 存储库。

为 GitHub Pages 创建 vite.config.js

GitHub Pages 期望从特定的基本 URL 提供应用程序，该 URL 通常是您的存储库名称。更新 vite.config.js 文件以反映这一点：

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

export default defineConfig({
  base: process.env.NODE_ENV === 'production' ? '/your-repo-name/' : '/',
  plugins: [react()],
})

base 选项确保应用程序在部署时使用正确的基本路径。

第 2 步：构建和部署项目

您需要安装 gh-pages 包来处理部署。

npm install gh-pages --save-dev

在 package.json 中，添加以下脚本以自动执行部署过程：

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

运行部署：

npm run deploy

此时，您的项目应该位于 https://.github.io//，但如果您像我一样，您可能会遇到一些问题应用程序无法正确渲染，或图像未显示。

第三步：常见问题及解决方案

问题一：部署后出现空白页

部署后，您可能会注意到应用程序加载了一个空白页面。这通常是由路由问题引起的。默认情况下，使用react-router-dom中的BrowserRouter，它依赖于服务器端路由，但GitHub Pages提供静态文件，不处理客户端路由。

解决方案：使用HashRouter

要解决此问题，请在 index.js 或 main.jsx 文件中从 BrowserRouter 切换到 HashRouter。

注意：您没有必要拥有它，它只是一个我在项目中经常使用的方便的 UI 库。

import { HashRouter } from 'react-router-dom';

createRoot(document.getElementById('root')).render(
  
    
      
        
      
    
  
);

HashRouter 在 URL 中使用井号 (#) 来跟踪导航状态，允许 GitHub Pages 正确服务不同的路由，而不会返回 404。

问题2：刷新或其他路由出现404错误

修复空白页问题后，您可能面临的另一个问题是应用程序在主页上运行，但在导航到其他路线时显示 404 错误，特别是当您直接访问 /blogs 或 /projects 等路线时。

发生这种情况是因为 GitHub Pages 只知道如何提供 index.html 文件，而无法识别由 React Router 管理的路由。

解决方案：在 GitHub Pages 设置中处理 404 错误

要解决此问题，您需要在 public/ 文件夹中创建一个 404.html 文件。该文件将确保 GitHub Pages 为您的 index.html 文件提供它无法识别的任何路由，从而允许 React Router 处理路由：

1. 将您的index.html复制到名为404.html的新文件中。
2. 将此文件放入您的 public/ 文件夹中。
3. 重建并重新部署项目。

问题 3：生产环境中图像未加载

最常见的部署问题之一是图像加载不正确。虽然它们在本地主机上运行良好，但在部署到 GitHub Pages 后您可能会注意到图像链接损坏。

例如，您可以在组件中引用如下图像：

问题：图像路径不正确

这里的问题是，当应用程序部署在子目录（例如 /your-repo-name/）中时，绝对路径（以 / 开头）无法正常工作。 GitHub Pages 尝试在 https://.github.io/Images/myImage.png 而不是 https://.github.io/your-repo-name/Images/myImage.png 查找图像，导致 404 错误。

解决方案：使用 BASE_URL

要解决此问题，请将所有图像移至公共/图像中，虽然这是可选的，但我强烈建议您这样做。您将根据环境动态地将 BASE_URL 添加到图像路径：

1. 定义一个依赖于环境的BASE_URL常量：

   const BASE_URL = import.meta.env.BASE_URL;

1. 引用图像时使用此 BASE_URL：

注意：不要忘记删除 Images 前面的 /，否则它会加倍，一个来自 BASE_URL，另一个来自您忘记删除的 /Images。

这可确保在开发 (localhost) 和生产 (GitHub Pages) 中使用正确的路径。

第 4 步：最终部署

实施路由和图像路径修复后，重建并重新部署您的应用程序：

npm run build
npm run deploy

您的 Vite/React 应用程序现在应该已完全部署，所有图像均已正确渲染，所有路由均已正确处理。

总之：

1. 路由问题：在 GitHub Pages 等静态部署中使用 HashRouter 进行正确路由。
2. 路由上的 404 错误：创建 404.html 文件以确保 GitHub Pages 正确为您的应用程序提供服务。
3. 图像未加载：将所有图像移至 Public/Images 并将 BASE_URL 动态附加到您的资源路径以处理开发和生产环境。

通过这些步骤，您的 Vite/React 应用程序应该可以在 GitHub Pages 上正常运行并顺利运行。祝您编码和部署愉快！