如何在GitHub仓库(paul.github.io)运行基于npm的Three.js网页？

本地预准备 #

• 在本地项目根目录执行 npm run build，确认生成 dist 目录，该目录下是编译完成的静态网页文件。

方案一：手动部署 #

• 打开你的GitHub仓库（paul.github.io），若仓库内已有项目代码，建议先备份；将本地 dist 目录下的所有文件上传至仓库的 main 分支（个人主页仓库默认部署 main 分支的根目录内容）。若不想覆盖原项目代码，可创建 gh-pages 分支，将 dist 内容上传至该分支。
• 进入仓库的 Settings 页面，找到 Pages 选项：
  • 选择部署分支：上传到 main 就选 main，上传到 gh-pages 就选 gh-pages。
  • 选择部署目录：均选择 /root。
  • 保存设置后等待3-5分钟，GitHub会自动完成部署，访问 https://paul.github.io 即可查看页面。

方案二：GitHub Actions自动部署（推荐） #

这种方式可以实现每次提交代码后自动完成构建和部署，无需手动操作：

• 在本地项目根目录创建 .github/workflows/deploy.yml 文件，写入以下内容：

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ] # 监听main分支的代码推送

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20' # 替换为你本地使用的Node.js版本

      - name: Install dependencies
        run: npm install

      - name: Build project
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist # 指定构建产物目录
          publish_branch: gh-pages # 部署到gh-pages分支

• 将该文件提交并推送到仓库的 main 分支。
• 进入仓库 Settings 的 Pages 选项，将部署分支改为 gh-pages，目录选 /root，保存设置。
• 之后每次向 main 分支推送代码，GitHub Actions会自动执行「安装依赖→构建项目→部署」的全流程。

注意事项 #

• 确认项目的 package.json 中，build 命令的产物确实输出到 dist 目录，若不是，需修改 deploy.yml 里的 publish_dir 为对应目录。
• 若部署后页面空白，打开浏览器控制台查看报错，大概率是资源路径问题。比如Vite项目，可在 vite.config.js 中设置 base: './' 来适配相对路径。

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