Vue项目部署GitHub Pages后本地图片无法显示求助

问题原因 #

本地开发时项目以根路径/运行，资源路径解析正常；但部署到GitHub Pages后，项目运行在/仓库名/的子路径下，打包后的资源路径未适配这个子路径，导致服务器找不到图标资源，返回404。

解决步骤 #

1. 配置项目基础路径（Vue CLI项目） #

在项目根目录创建或修改vue.config.js，添加publicPath配置：

module.exports = {
  publicPath: process.env.NODE_ENV === 'production'
    ? '/你的仓库名称/' // 替换为你的GitHub仓库名，例如'/vue-link-buttons/'
    : '/'
}

该配置会让生产环境打包时，所有资源路径自动加上仓库名前缀，适配GitHub Pages的子路径结构。

2. 调整图标引用逻辑（可选优化） #

当前代码在computed中直接用require('@/assets/xxx.png')引入图标，本地正常但打包后可能因路径解析出错。可改为传递路径字符串，在组件内动态引入：

• 修改computed中的按钮数组：

get_button_array() {
  const button_array = [
    { name: "會員", icon: '@/assets/member.png' },
    { name: "優惠卷", icon: '@/assets/coupon.png' },
    { name: "積點", icon: '@/assets/point.png' },
    { name: "問卷", icon: '@/assets/form.png' },
    { name: "集點卡", icon: '@/assets/card.png' },
    { name: "抽獎", icon: '@/assets/lottery.png' },
    { name: "寄存卡", icon: '@/assets/storage.png' },
    { name: "行銷活動", icon: '@/assets/event.png' },
    { name: "儲值信託", icon: '@/assets/deposit.png' },
    { name: "履約票卷", icon: '@/assets/ticket.png' },
  ]
  return button_array;
}

• 修改link_button组件的模板：

<template>
  <div class="link_button button_notLogin" v-if="!loginState">
    <img :src="icons[button_index]" class="link_button_icon" />
    <p>{{ title }}</p>
  </div>
  <div class="link_button" v-else>
    <img :src="require(icon)" class="link_button_icon" />
    <p>{{ title }}</p>
  </div>
</template>

如果是Vite项目，替换require为new URL(icon, import.meta.url).href：

<img :src="new URL(icon, import.meta.url).href" class="link_button_icon" />

3. 确认GitHub Pages部署设置 #

• 执行npm run build打包项目，生成dist文件夹。
• 将dist文件夹内的所有文件推送到GitHub仓库的gh-pages分支（可使用gh-pages -d dist命令快速部署）。
• 进入仓库「Settings」→「Pages」页面，确认部署来源选择gh-pages分支，根目录为/root。

验证 #

部署完成后刷新GitHub Pages页面，图标应能正常加载，不再出现404错误。

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