解决Github Pages不加载Vue框架项目静态文件问题

在使用Vue框架开发项目并部署到Github Pages时，很多开发者都会遇到一个头疼的问题：页面能够正常访问，但项目中的JS、CSS等静态文件却无法加载，导致页面样式错乱、功能失效。其实这个问题的核心在于静态文件的路径配置不当，本文将详细介绍如何通过配置打包工具的路径以及Github Pages设置来解决这一问题，并分别以Vite和Webpack两种常用打包工具进行演示。

一、问题原因分析

Github Pages部署的项目，其访问路径通常是 https://[用户名].github.io/[项目名]/，而Vue项目默认的静态文件路径是基于根目录（/）的。当项目部署到Github Pages后，静态文件会被请求从根目录获取，而实际静态文件却在/[项目名]/目录下，这就导致了路径不匹配，静态文件加载失败。

二、不同打包工具的配置方法

解决该问题的关键是修改打包工具的静态文件公共路径（publicPath），使其指向Github Pages的项目地址。

如果你不想打包，直接在根目录下有一个index.html静态网页文件。那么将里面js,css等静态文件的引用路径前面加上/[项目名]/即可。例如：/static/js/app.js —> /[项目名]/static/js/app.js 如果成功则无需打包

下面分别介绍Vite和Webpack的配置步骤。

2.1 Vite打包工具配置

Vite是目前Vue项目常用的构建工具，配置方式较为简洁，只需修改项目根目录下的vite.config.js文件。

找到vite.config.js文件：该文件位于Vue项目的根目录下，如果没有则手动创建。
配置publicPath：在defineConfig对象中添加base属性（Vite中publicPath对应的是base），其值设置为你的Github Pages项目地址。格式为 'https://[用户名].github.io/[项目名]/'，例如如果用户名为testuser，项目名为vue-demo，则配置为 base: 'https://testuser.github.io/vue-demo/'。
设置打包输出目录：默认情况下Vite打包输出到dist目录，我们需要将其改为docs目录，方便后续Github Pages配置。在defineConfig中添加build选项，设置outDir: 'docs'。

配置完成后的vite.config.js文件示例如下：


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

export default defineConfig({
  plugins: [vue()],
  base: 'https://testuser.github.io/vue-demo/', // 替换为你的项目地址
  build: {
    outDir: 'docs' // 打包输出到docs目录
  }
})

base路径不唯一可自行在浏览器控制台中查看请求路径将请求路径调整为 https://<你的名称>.github.io/<项目名称>/静态文件路径。即可
配置完成后，执行npm run build命令进行打包，此时项目根目录下会生成docs文件夹，里面包含了打包后的静态文件。

2.2 Webpack打包工具配置（Vue CLI项目）

如果你的Vue项目是使用Vue CLI创建的，那么使用的打包工具是Webpack，需要修改vue.config.js文件。

找到vue.config.js文件：该文件位于Vue项目的根目录下，若不存在则手动创建。
配置publicPath：在配置对象中添加publicPath属性，值设置为你的Github Pages项目地址，格式与Vite相同，即 'https://[用户名].github.io/[项目名]/'。
设置打包输出目录：同样将打包输出目录改为docs，在配置对象中添加outputDir: 'docs'。

配置完成后的vue.config.js文件示例如下：


module.exports = {
  publicPath: 'https://testuser.github.io/vue-demo/', // 替换为你的项目地址
  outputDir: 'docs' // 打包输出到docs目录
}

执行npm run build命令打包，项目根目录会生成docs文件夹，包含打包后的静态资源。

三、Github Pages配置步骤

完成打包工具配置并生成docs文件夹后，需要在Github仓库中设置Github Pages的部署源。

推送代码到Github仓库：将包含docs文件夹的项目代码推送到Github仓库的main分支（或你使用的主分支）。
进入仓库设置：打开你的Github项目仓库，点击右上角的Settings选项。
找到Github Pages设置：在左侧导航栏中找到Pages选项并点击进入。
设置部署源：在Build and deployment下的Source选项中，选择Deploy from a branch。然后在Branch选项中，选择main分支，并在后面的文件夹选择框中选择/docs，点击Save保存设置。

设置完成后，Github Pages会自动部署你的项目，通常几分钟后即可通过https://[用户名].github.io/[项目名]/访问，此时JS、CSS等静态文件就能正常加载了。

四、常见问题排查

publicPath配置错误：确保publicPath（Vite中为base）的路径正确，末尾必须加上/，否则可能导致部分静态文件路径拼接错误。
docs文件夹未推送：检查是否将打包生成的docs文件夹推送到了Github仓库，若未推送则需要执行git add docs、git commit -m "add docs"、git push命令。
分支或文件夹选择错误：确认Github Pages设置中选择的分支是main（或你的项目主分支），文件夹是/docs。