企业官网建设流程全解析

Create React App 如何部署到 GitHub Pages 并解决客户端路由 404

【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app

把一个 Create React App 项目发布到 GitHub Pages 是最常见的静态托管需求，但如果应用使用了客户端路由（例如 React Router 的browserHistory），直接刷新子路由会得到 404。这篇文章按官方文档的操作路径完成两件事：配置homepage并通过gh-pages把npm run build的产物发布到项目页面，然后针对 pushState 路由在 GitHub Pages 上的 404 给出文档给出的两种处理方案。

适用前提：

• 项目由 Create React App 创建，react-scripts版本不低于 0.2.0（当前创建的新项目默认满足）；
• 本地机器 Node 版本 >= 14（服务器端不要求）；
• 部署目标是项目页（https://用户名.github.io/项目名）或用户页（https://用户名.github.io），文档对两者都给出了配置。

发布前的构建：build目录与部署提示

执行生产构建：

npm run build

该命令会把应用打包到build目录，build目录是 Create React App 输出的唯一产物。如果package.json中没有homepage字段，构建后终端会打印一份部署到 GitHub Pages 的说明（cheat sheet），提示补上homepage字段；如果已经配置，终端会打印npm run deploy相关的发布指引。构建提示逻辑见 printHostingInstructions.js，部署完整文档见 deployment.md。

第 1 步：在package.json中添加homepage（必做）

官方文档特别强调这一步：跳过它，应用不会正确部署。Create React App 用homepage字段来确定构建后 HTML 文件中的根 URL。

打开package.json，按页面类型添加字段：

项目页（最常见情况）：

"homepage": "https://myusername.github.io/my-app",

用户页：

"homepage": "https://myusername.github.io",

自定义域名页面：

"homepage": "https://mywebsite.com",

其中myusername、my-app、mywebsite.com是文档示例值，替换为你自己的 GitHub 用户名、仓库名或域名。

第 2 步：安装gh-pages并添加deploy脚本

在项目根目录安装gh-pages：

npm install --save gh-pages

使用 yarn 的项目用：

yarn add gh-pages

然后在package.json的scripts中加入两条脚本：

"scripts": { + "predeploy": "npm run build", + "deploy": "gh-pages -d build", "start": "react-scripts start", "build": "react-scripts build",

predeploy脚本会在deploy运行前自动执行，所以一次npm run deploy就完成了"先构建、再发布"。

可选分支：如果你部署的是用户页而不是项目页，需要把部署目标改为main分支：

"scripts": { "predeploy": "npm run build", - "deploy": "gh-pages -d build", + "deploy": "gh-pages -b main -d build",

第 3 步：运行npm run deploy发布

npm run deploy

运行后先执行predeploy（即npm run build），再由gh-pages -d build发布build目录。文档描述的发布目标是https://myusername.github.io/my-app这类地址，也就是说：npm run deploy成功执行的完成标准，是应用可以被访问到该 URL。

第 4 步：项目页需确认 GitHub Pages 源是gh-pages分支

如果部署的是项目页，最后还要在 GitHub 仓库的 Pages 设置中，把站点来源设为gh-pages分支，这样站点才会从发布脚本推送的分支取内容。用户页部署不需要这一步。

可选：配置自定义域名。在public/文件夹下添加CNAME文件，内容为你的域名，文档示例：

mywebsite.com

解决客户端路由 404：刷新子路由返回 404

如果你的应用用了基于 HTML5pushStatehistory API 的路由器（例如 React Router 使用browserHistory），开发服务器能正常响应localhost:3000/todos/42，但发布到 GitHub Pages 后，对http://user.github.io/todomvc/todos/42这样的地址做一次全新页面加载时，GitHub Pages 会返回 404——因为服务器并不知道/todos/42这个前端路由的存在。文档给出了两种解决方案：

方案 A：改用 hash 路由。把 React Router 的 history 切换为 hash 路由（hashHistory），URL 会变成形如http://user.github.io/todomvc/#/todos/42的形式，文档指出这种 URL 会更长、更啰嗦，但能避开 404。这是 GitHub Pages 上最直接的做法。

方案 B：404.html重定向。在部署前把一个带重定向代码的404.html文件放进build目录，并在index.html中加上处理重定向参数的代码，让 GitHub Pages 把 404 重定向回index.html。文档没有给出404.html的具体内容，只说明了这个机制并指向外部指南；如果你要采用这个方案，需要按该指南自行补齐文件内容。

另外两个文档提供的补充手段：

• 生产构建中，如果应用已经 opt-in 了 service worker，service worker 会自动接管/todos/42这类导航请求并返回缓存的index.html，可以通过eject后修改SWPrecachePlugin的navigateFallback、navigateFallbackWhitelist选项来调整或禁用这一行为。
• 如果路由库需要感知应用挂在子路径下，文档提到使用react-router@^4时可以在任意<Router>上设置basename，例如<BrowserRouter basename="/calendar"/>，此时<Link to="/today"/>渲染出的链接是/calendar/today。

对于没有使用 pushState 路由的应用，也可以把homepage设为"."（react-scripts@0.9.0及以上支持），让所有资源路径相对于index.html，应用就能从根路径移动到任意子路径而无需重新构建。

部署报错排查

npm run deploy过程中文档记录了两种典型报错及处理方式：

/dev/tty: No such a device or address：

1. 创建一个新的 Personal Access Token；
2. 执行git remote set-url origin https://<user>:<token>@github.com/<user>/<repo>（<user>换成你的 GitHub 用户名，<token>换成新建的 token，<repo>换成仓库名。注意这条命令会把 token 写进本地的 remote URL，之后如果 token 失效需要更新）；
3. 再次执行npm run deploy。

Cannot read property 'email' of null：

1. git config --global user.name '<your_name>'（替换为你的名字）；
2. git config --global user.email '<your_email>'（替换为你的邮箱）；
3. 再次执行npm run deploy。

结果确认

• 访问https://myusername.github.io/my-app（或你的用户页/自定义域名地址），应用能打开，静态资源正常加载，说明homepage配置与发布流程正确；
• 若使用了 hash 路由方案，直接在浏览器地址栏输入带#的子路由地址（如https://myusername.github.io/my-app/#/todos/42）并刷新，页面应由前端路由接管而不是返回 404；
• 若仍遇到 404，对照本文"解决客户端路由 404"一节确认路由模式，以及项目页是否已将 Pages 来源设为gh-pages分支。

完整部署文档（含静态服务器、Apache.htaccess等其他托管方案）见 deployment.md，路由配置见 adding-a-router.md，npm run build的行为说明见 available-scripts.md。

【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app