Vue多页面应用部署至GitHub Pages遇问题，求部署方案

一、标准多页面项目目录结构 #

先确保你的项目目录符合多页规范，示例如下：

vue-multi-page/
├── public/
│   ├── index.html       # 首页模板
│   └── about.html       # 关于页模板
├── src/
│   ├── pages/
│   │   ├── index/
│   │   │   ├── main.js  # 首页入口文件
│   │   │   └── App.vue  # 首页根组件
│   │   └── about/
│   │       ├── main.js  # 关于页入口文件
│   │       └── App.vue  # 关于页根组件
│   └── components/       # 公共组件目录
└── vue.config.js

二、正确配置vue.config.js #

多页面应用的核心是pages配置项，同时要适配GitHub Pages的路径规则：

module.exports = {
  // 生产环境下设置为仓库名称，确保资源路径正确
  publicPath: process.env.NODE_ENV === 'production'
    ? '/your-repo-name/' // 替换成你的GitHub仓库名称
    : '/',
  // 多页面配置，每个页面对应一个配置项
  pages: {
    index: {
      entry: 'src/pages/index/main.js', // 页面入口
      template: 'public/index.html',    // 模板文件
      filename: 'index.html',           // 打包后输出文件名
      title: '首页'                     // 页面标题
    },
    about: {
      entry: 'src/pages/about/main.js',
      template: 'public/about.html',
      filename: 'about.html',
      title: '关于页'
    }
    // 新增页面直接按上述格式添加即可
  },
  // 关闭生产环境sourceMap，减少打包体积并避免加载异常
  productionSourceMap: false
}

三、配置部署脚本 #

1. 安装部署依赖：

npm install gh-pages --save-dev

2. 在package.json中添加部署脚本：

{
  "scripts": {
    "build": "vue-cli-service build",
    "deploy": "gh-pages -d dist"
  }
}

四、执行部署 #

1. 先打包项目，生成生产环境文件：

npm run build

2. 推送打包后的dist目录到GitHub Pages分支：

npm run deploy

3. 打开GitHub仓库的Settings -> Pages，设置Source为gh-pages分支、根目录，保存后等待1-2分钟即可访问。

五、常见问题修复 #

• 白屏/资源404：检查publicPath是否设置为仓库名称，确保打包后dist目录下的html文件中，资源路径是/your-repo-name/xxx.js格式
• 组件不显示：检查页面入口main.js是否正确挂载Vue实例，模板html中是否存在对应的<div id="app"></div>容器
• 页面跳转异常：多页面应用间跳转需用绝对路径，比如/your-repo-name/about.html，避免相对路径导致的404

内容的提问来源于stack exchange，提问作者Matthattan