GitHub Pages站点如何在docs目录页面引用同仓库src目录下的JS文件？

问题原因 #

你遇到的404问题本质是两个原因叠加导致的：

• GitHub Pages设置发布源为master分支的/docs子目录时，只有/docs目录下的内容会被部署到线上服务器，仓库根目录下的/src目录根本不会被同步到Pages环境，不管路径怎么写都不可能访问到
• 线上环境的站点根路径是https://(my-username).github.io/(my-repo-name)/，对应本地仓库的/docs目录，因此../src/Main.js的相对路径在线上会解析为https://(my-username).github.io/src/Main.js，路径本身也不符合线上的目录结构

通用解决方案（本地、线上均兼容） #

方案1：调整目录结构（无构建工具的小型项目首选）

直接把/src目录整体移动到/docs目录下，调整后的项目结构为：

/
 docs/
      index.html
      src/
          Main.js
          ... (other .js files) ...
 README.md
 ...

之后把index.html里的引用路径改为./src/Main.js即可，本地打开/docs/index.html可以正常加载，线上Pages也会把src目录作为docs的子目录一起发布，路径完全匹配。

方案2：配置构建规则（有打包工具的项目首选）

如果你用Vite、Webpack、Rollup等打包工具，直接修改构建配置，把打包后的JS产物输出到/docs目录下的子目录（比如/docs/assets/js/），源代码依然可以留在/src目录做开发。
之后index.html里引用打包后的JS路径即可，比如./assets/js/Main.js，本地开发调试和线上发布都不需要额外修改路径。

方案3：用GitHub Action自动同步文件（不想改本地结构的首选）

如果不想调整本地的目录结构，也不想改开发习惯，可以加一个简单的GitHub Action工作流，每次往master分支推送代码时，自动把根目录的/src目录复制到/docs目录下：

name: Sync src to docs
on:
  push:
    branches: [ master ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Copy src to docs
        run: cp -r ./src ./docs/src
      - name: Commit and push changes
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          git add .
          git commit -m "chore: sync src to docs" || exit 0
          git push

配置后本地依然可以用原路径调试，线上部署的docs目录下也会有同步后的src文件，不需要修改引用路径即可兼容双环境。

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