Vue3+Vite项目部署GitHub Pages报错：无法解析模块标识符‘vue’

问题原因 #

出现Uncaught TypeError: Failed to resolve module specifier "vue"错误，本质是两点：一是main.js缺少Vue核心方法的导入，二是Vite构建时未配置适配GitHub Pages的基础路径，导致浏览器无法正确解析模块引用。

修复步骤 #

• 补全main.js的核心导入
  你的main.js未导入Vue的createApp方法，修正代码如下：

  import { createApp } from 'vue'
  import './style.css'
  import App from './App.vue'
  
  createApp(App).mount('#app')
  

• 配置Vite的base路径
  GitHub Pages的访问路径为https://<用户名>.github.io/<仓库名>/，需在vite.config.js中设置base属性适配：

  import { defineConfig } from 'vite'
  import vue from '@vitejs/plugin-vue'
  
  export default defineConfig({
    plugins: [vue()],
    base: '/<你的仓库名称>/' // 替换为实际GitHub仓库名，例如'/my-portfolio/'
  })
  

• 规范构建与部署流程

  1. 确认package.json的构建脚本正确：

     "scripts": {
       "dev": "vite",
       "build": "vite build",
       "preview": "vite preview"
     }
     

  2. 执行npm run build生成dist构建产物文件夹
  3. 用npm run preview本地预览构建结果，验证正常后再部署
  4. 将dist文件夹内的所有文件推送到GitHub仓库的gh-pages分支

• 检查GitHub Pages部署设置
  在仓库的Settings -> Pages页面，确认部署来源选择gh-pages分支的/root目录。

额外提示 #

• 必须部署构建后的dist文件，不要直接推送源码
• 若项目使用Vue Router，需设置路由的base属性并启用hash模式，避免页面刷新后404

内容的提问来源于stack exchange，提问作者Dev-kun