使用Vite的项目在GitHub Pages及本地打开均无法渲染问题求助

核心问题根源 #

你用npm run dev能正常运行，是因为Vite的开发模式基于本地HTTP服务器，会自动处理ES模块的路径解析、依赖加载逻辑。但直接打开本地index.html（file://协议）或者把开发源码直接上传GitHub Pages，会触发两个关键问题：

1. ES模块路径解析失败：开发环境的模块导入路径是相对服务器根目录的，用本地文件协议打开时，浏览器会把路径解析成本地文件路径，导致找不到JS模块；
2. 未生成生产静态文件：你上传的是源码，不是Vite编译后的产物，源码里的index.html引用的是开发环境入口，不是能直接运行的打包后JS。

具体解决步骤 #

1. 构建生产版本 #

在项目根目录执行命令，生成可直接部署的静态文件：

npm run build

执行完成后会得到一个dist文件夹，里面的文件才是能在静态托管环境运行的产物。

2. 部署到GitHub Pages #

两种方式选其一即可：

• 手动部署：把dist文件夹内的所有文件，上传到仓库的gh-pages分支，再在仓库设置里将GitHub Pages的源改为gh-pages分支；
• 自动部署（推荐）：在仓库根目录创建.github/workflows/deploy.yml文件，粘贴以下内容（主分支是main则无需修改）：

name: 自动部署到GitHub Pages
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: 安装依赖
        run: npm install
      - name: 构建生产文件
        run: npm run build
      - name: 部署到Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

之后每次提交代码到主分支，GitHub会自动完成构建并部署到Pages。

3. 本地验证静态文件 #

构建完成后不要直接打开dist/index.html，用本地静态服务器测试才准确，比如：

npx serve dist

这样能模拟GitHub Pages的运行环境，确认功能正常。

额外注意事项 #

• 如果你的GitHub Pages地址是https://用户名.github.io/仓库名/这种子路径形式，必须在vite.config.js里配置base：

export default {
  base: '/The-Planets/'
}

否则构建后的资源路径会出错，找不到JS/CSS文件；

• 确保仓库的.gitignore包含node_modules/，这个文件夹无需上传，既占空间又无意义。

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