Vue-cli项目部署GitHub Pages方法及Webpack构建项目空白页问题

我来给你梳理两种最实用的部署方式，你可以根据自己的习惯选择：

方式一：通过docs文件夹手动部署 #

• 先在项目根目录执行 npm run build，生成打包后的dist文件夹，里面是所有可直接部署的静态资源。
• 你可以直接把dist重命名为docs，或者更高效的方式是在vue.config.js里配置打包输出目录：

  module.exports = {
    outputDir: 'docs', // 让打包文件直接输出到docs文件夹
    publicPath: './'    // 关键设置：用相对路径避免部署后资源找不到
  }
  

• 把所有代码（包括新生成的docs文件夹）提交并推送到GitHub仓库的主分支（master或main）。
• 打开仓库的Settings页面，下拉找到GitHub Pages区域，在Source选项中选择「master branch /docs folder」（对应你的主分支），保存后等待几分钟，就能通过页面上给出的链接访问部署好的项目了。

方式二：用gh-pages分支自动部署 #

这种方式不用手动处理文件夹，适合频繁更新部署的场景：

• 先安装依赖包：npm install gh-pages --save-dev。
• 同样在vue.config.js里配置publicPath: './'（路径问题是部署坑的重灾区，一定要加）。
• 打开package.json，在scripts里添加两个命令：

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

• 执行 npm run deploy，它会自动帮你打包项目，然后把dist里的内容推送到仓库的gh-pages分支。
• 回到GitHub仓库Settings的GitHub Pages区域，选择gh-pages分支作为Source，保存即可完成部署。

你遇到的空白页+控制台异常，大概率是路径配置或者路由模式的问题，我给你几个排查和解决的方向：

1. 检查publicPath配置 #

Vue-cli默认打包后的静态资源路径是根路径（/），但GitHub Pages的项目是部署在https://你的用户名.github.io/仓库名/这样的子路径下，所以必须调整相对路径：

• 打开vue.config.js，添加或修改：

  module.exports = {
    publicPath: process.env.NODE_ENV === 'production' ? '/你的仓库名称/' : '/'
  }
  

  如果不想区分开发/生产环境，直接写publicPath: './'也能解决大部分路径问题。

2. 检查路由模式 #

如果你的项目用了history模式的路由，GitHub Pages不支持这种模式的直接访问和刷新（会返回404，导致页面空白）。解决办法：

• 最简单的是改成hash模式：在router/index.js里修改：

  const router = new VueRouter({
    mode: 'hash', // 把原来的history改成hash
    routes: [...]
  })
  

• 要是你坚持用history模式，需要在打包后的文件夹（docs或dist）里新建一个404.html，内容和index.html完全一致，同时在GitHub Pages设置里开启Custom domain（新手还是推荐先用hash模式，省事儿）。

3. 确认文件是否完整提交 #

有时候.gitignore文件里可能包含了dist或docs，导致打包后的文件没被推送到GitHub。你可以去仓库页面看看docs文件夹里有没有index.html和静态资源文件，如果没有，就修改.gitignore，把docs/或dist/这一行删掉，然后重新提交推送。

4. 分析控制台错误 #

你提到控制台有异常，把具体的错误信息贴出来能更快定位问题。比如如果是“404 资源加载失败”，那就是路径不对，按上面的publicPath配置改就行；如果是路由相关的报错，就检查路由模式的设置。

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