使用Parcel+React部署GitHub Pages生产SPA遇问题求指导

我之前也碰到过一模一样的情况——用Parcel打包后部署到GitHub Pages总是加载失败，但用Create React App就能正常跑，后来发现核心问题是资源路径配置和打包参数没适配GitHub Pages的环境，下面是亲测有效的完整操作步骤：

1. 先配置项目的 homepage 字段 #

在你的package.json里添加homepage字段，值对应你的GitHub Pages访问路径：

• 如果是普通仓库，格式为https://<你的GitHub用户名>.github.io/<仓库名>/
• 如果是用户/组织主页仓库（仓库名是<用户名>.github.io），直接写https://<你的GitHub用户名>.github.io/

示例：

{
  "name": "my-parcel-react-app",
  "homepage": "https://mugetsu.github.io/my-parcel-react-app/",
  // ... 其他原有字段
}

2. 修改Parcel的打包命令 #

Parcel默认会把静态资源的路径设为根目录/，但GitHub Pages部署在子路径下时，这个路径就会失效。所以打包时必须加上--public-url参数，指定为你的仓库路径（根域名仓库则写/）。

把package.json里的build命令更新为：

"scripts": {
  "dev": "parcel index.html",
  "build": "parcel build index.html --public-url /<你的仓库名>/"
}

3. 安装并配置gh-pages插件 #

先安装依赖：

npm install gh-pages --save-dev

接着在package.json的scripts里添加两个部署相关的命令：

"scripts": {
  // ... 原有脚本
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

• predeploy会在deploy命令执行前自动触发打包，确保部署的是最新生产代码
• gh-pages -d dist是把Parcel打包生成的dist目录内容推送到GitHub的gh-pages分支

4. 执行部署 #

运行下面的命令就能完成部署：

npm run deploy

额外注意：路由适配（如果用了React Router） #

如果你的应用用了BrowserRouter，GitHub Pages刷新页面会出现404，这时候可以二选一解决：

• 改用HashRouter：路由会带上#，不会触发GitHub Pages的404逻辑
• 添加404.html文件：在项目根目录创建和index.html内容完全一致的404.html，Parcel打包时会自动包含它，GitHub Pages会在找不到页面时返回这个文件，让React Router接管路由处理

为什么Create React App能直接成功？ #

因为CRA已经内置了对homepage字段的适配逻辑，打包时会自动根据这个字段调整所有静态资源的引用路径，而Parcel需要我们手动通过--public-url参数来完成这个适配。

按照上面的步骤操作后，你的应用应该就能正常在GitHub Pages加载了！

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