React Boilerplate 部署实战指南：Heroku、AWS S3、子目录与 Elastic Beanstalk 全流程

React Boilerplate 部署实战指南Heroku、AWS S3、子目录与 Elastic Beanstalk 全流程【免费下载链接】react-boilerplate A highly scalable, offline-first foundation with the best developer experience and a focus on performance and best practices.项目地址: https://gitcode.com/gh_mirrors/rea/react-boilerplate本篇部署指南以 React Boilerplatedocs/general/deployment.md为核心骨架系统讲解将生产构建产物发布到 Heroku、AWS S3、现有服务器子目录以及 AWS Elastic Beanstalk 的完整流程。文章不仅复现每一步可复制的命令与配置文件还结合仓库源码webpack 构建配置、Express 生产中间件、npm scripts说明每条指令背后的运行原理帮助读者在理解构建-托管链路的基础上独立完成任意一种生产部署。部署前的准备理解构建产物与生产启动命令在进入各平台部署之前需要先理解 React Boilerplate 生产环境的两条核心链路生产构建与生产启动它们是所有部署方案共同依赖的基础。生产构建由 package.json 中的build脚本驱动build: cross-env NODE_ENVproduction webpack --config internals/webpack/webpack.prod.babel.js --color -p --progress --hide-modules --display-optimization-bailout该命令会调用 internals/webpack/webpack.prod.babel.js以 internals/webpack/webpack.base.babel.js 为公共配置进行生产打包。产物默认输出到仓库根目录下的./build文件夹build:clean脚本会先清理旧产物并额外产出 gzip 压缩包与离线缓存相关的 Service Worker 文件offline-plugin与compression-webpack-plugin详见 webpack.prod.babel.js。生产启动由start:prod脚本驱动start:prod: cross-env NODE_ENVproduction node server它启动 server/index.js 中的 Express 服务。在NODE_ENVproduction时server/middlewares/frontendMiddleware.js 会加载addProdMiddlewaresserver/middlewares/addProdMiddlewares.js其核心逻辑包括使用compression()对响应做 gzip 压缩通过express.static(outputPath)以publicPath默认/对外提供./build目录下的静态资源对任意未被静态资源匹配的路由回退返回index.html保证前端路由react-router在刷新页面时也能正确加载。默认监听端口由 server/port.js 决定优先取命令行--port参数其次取环境变量PORT最后回退到3000。理解了这两条链路下面各平台的部署步骤就一目了然平台只负责托管构建产物或运行生产服务。Heroku三步完成部署Heroku 是一个托管 PaaS 平台它直接运行 Node.js 服务进程因此部署 React Boilerplate 的核心是让 Heroku 执行start:prod而非默认的start。第 1 步创建 Procfile在项目根目录创建名为Procfile的文件写入web: npm run start:prod原因Heroku 默认以npm run start作为 Node.js 应用的启动命令而start脚本运行的是开发模式cross-env NODE_ENVdevelopment node server。必须通过 Procfile 覆盖默认启动命令让 Heroku 以NODE_ENVproduction启动生产服务。第 2 步安装 Node.js buildpack为你的 Heroku 应用设置 Node.js buildpackheroku buildpacks:set https://github.com/heroku/heroku-buildpack-nodejs#v133 -a [your app name]其中#v133是 buildpack 版本标签请务必替换为当时最新的 buildpack 版本以官方 releases 页发布的最新版本为准。buildpack 负责在 Heroku 上安装 Node.js 与 npm 依赖npm install然后执行Procfile中声明的命令。第 3 步标准 Git 推送流程git add . git commit -m Made some epic changes as per usual git push heroku mastergit push heroku master会触发 Heroku 构建拉取代码 → 安装依赖 → 运行 buildpack 钩子。由于start:prod在启动时才执行node server而生产静态资源依赖npm run build生成的./build目录——如果构建目录未提交到仓库建议在package.json中补充postinstall钩子如postinstall: npm run build让平台在安装依赖后自动构建或确保./build产物已纳入版本控制。这一点在不同平台的构建行为上略有差异需要结合自身 CI/CD 策略确认。AWS S3七步完成静态托管S3 只负责托管静态文件不运行 Node.js 进程。因此 S3 方案的核心是在本地构建出./build目录再把它作为静态网站整体上传。第 1 步本地构建npm install npm run build执行后会在项目根目录生成./build文件夹。注意 webpack.base.babel.js 中的默认输出配置output: Object.assign( { // Compile into js/build.js path: path.resolve(process.cwd(), build), publicPath: /, }, options.output, ),即产物输出到./build资源引用路径以站点根目录/为基准。publicPath为/意味着所有 JS/CSS 资源都以绝对路径引用因此必须配合根路径访问直接通过 S3 静态网站端点访问或绑定自定义域名才能正确加载资源——这也正是下文子目录部署需要显式修改publicPath的原因。第 2 步创建 S3 Bucket登录 AWS 控制台在Services下拉菜单中选择S3进入 S3 服务。第 3 步创建存储桶点击Create Bucket填写Bucket Name全局唯一与Region区域美国地区官方文档推荐US Standard即us-east-1。点击Create完成创建。第 4 步开放公共读权限选中刚创建的 Bucket在右侧Properties选项卡下打开Permissions手风琴。点击Add more permissions将Grantee设为Everyone或任何需要访问网站的主体授予View Permissions读权限点击Save。只有公开可读静态网站端点才能向匿名访客提供页面内容。第 5 步开启静态网站托管打开Static Website Hosting手风琴这里会显示网站的 URLendpoint形如example.s3-website-us-east-1.amazonaws.com。点击Enable website hosting在Index document与Error document两个输入框中都填写index.html点击Save。说明SPA 应用没有真正的404 页面Error document同样指向index.html是为了让前端路由如/about在直接访问或刷新时能回退到应用入口由 react-router 接管后续渲染——这与生产中间件中app.get(*, ...)回退返回index.html的原理一致addProdMiddlewares.js。第 6 步上传构建产物并设为公开在 Bucket 列表左侧点击该 Bucket 进入点击Upload选择./build文件夹内的所有文件点击Start Upload。上传完成后全选文件右键或点击Actions按钮选择Make Public将全部对象设为公开可读。第 7 步验证访问点击Properties选项卡打开Static Website Hosting点击其中的Endpoint链接。应用即应运行在该 URL 上。注意S3 静态网站端点不支持 HTTP 强制跳转 HTTPS如需 HTTPS 与自定义域名可配合 CloudFront CDN 分发为 Bucket 配置源站并在 Route 53 中绑定域名与证书。此为 S3 托管的最佳实践补充官方文档亦推荐此路线。部署到已有服务器的子目录如果你想把应用部署在已有服务器Apache / NGINX的一个子路径下例如用户通过https://host/web-app访问应用则需要让前端构建与路由同时感知该子路径。文档说明这一方案已在 APACHE 与 NGINX 服务器上验证通过。整个改动分为四步。第 1 步让 webpack 注入环境变量修改 internals/webpack/webpack.base.babel.js在文件顶部引入两个可被环境变量覆盖的常量 const BUILD_FOLDER_PATH process.env.BUILD_FOLDER_PATH || build; const PUBLIC_PATH process.env.PUBLIC_PATH || /;然后将output配置中的默认值替换为上述常量- path: path.resolve(process.cwd(), build), - publicPath: /, path: path.resolve(process.cwd(), BUILD_FOLDER_PATH), publicPath: PUBLIC_PATH,最后在文件底部的EnvironmentPlugin中注入默认值webpack.base.babel.js 中现有插件为NODE_ENV在此追加# inside EnvironmentPlugin PUBLIC_PATH: /,原理webpack.EnvironmentPlugin会把process.env.PUBLIC_PATH的值在编译期注入到前端代码中NODE_ENV即是现有用法webpack.base.babel.js。这样构建时若设置了PUBLIC_PATH/web-app/所有资源引用的绝对路径前缀就会自动变为/web-app/同时process.env.PUBLIC_PATH在浏览器端代码里也能被正确替换。第 2 步为路由 history 添加 basename修改 app/utils/history.js将createBrowserHistory的调用改为传入 basename- const history createHistory(); const basename process.env.PUBLIC_PATH; const history createHistory({ basename });仓库中 app/utils/history.js 当前实现为import { createBrowserHistory } from history; const history createBrowserHistory(); export default history;原理浏览器 History API 没有子目录概念路由路径/web-app/about中的/web-app只是前缀。history库的basename选项会在匹配路由时剥离该前缀使应用内部仍然只感知/about同时PUBLIC_PATH由 webpack 在构建期替换为真实值如/web-app/从而让 history 与静态资源前缀保持一致。第 3 步构建到指定子目录PUBLIC_PATH/web-app/ BUILD_FOLDER_PATHbuild/web-app npm run build执行后生产构建产物会输出到./build/web-app目录且所有资源引用与路由 basename 都以/web-app/为前缀。注意PUBLIC_PATH末尾的斜杠是必须的/web-app/而非/web-app否则拼接出的资源路径会出错。第 4 步上传到服务器 web-root将生成的web-app文件夹整体上传/放置到服务器的 web-root 目录下最终端点即为https://host/web-app服务器侧要求Apache / NGINX 需允许对该子目录的目录访问如 Apache 的AllowOverride与静态文件访问配置。由于 SPA 路由回退仍需index.html建议同时配置子目录下的重写规则如 Apache 的RewriteRule或 NGINX 的try_files ... /index.html避免直接访问/web-app/about时返回 404。AWS Elastic BeanstalkElastic Beanstalk 方案的核心思路与 Heroku 类似——平台运行 Node.js 进程因此关键在于让平台以生产模式启动。完整背景可参考仓库维护者整理的 issue #2566原文链接见 deployment.md。前置条件创建 AWS 账号并登录 AWS 控制台安装 EB CLI官方文档提供 CLI-only 安装方式配置 AWS EB Profile若使用持续部署工具可为 CD 工具单独创建一个用户通过 CLI 或 Web 控制台创建 Elastic Beanstalk 的 Application 与 Environment配置 EB CLI正确配置后本地应存在.elasticbeanstalk/config.yml文件。配置步骤第 1 步在 package.json 中添加 AWS EB 启动脚本aws-eb:prod: npm run build npm run start:prod该脚本先在平台实例上执行生产构建再以生产模式启动服务。第 2 步创建.ebextensions/aws.config文件# 详见 react-boilerplate issue #2566 option_settings: aws:elasticbeanstalk:container:nodejs: NodeCommand: npm run aws-eb:prod aws:elasticbeanstalk:application:environment: NPM_USE_PRODUCTION: false说明NodeCommand覆盖 EB 平台默认的 Node 启动命令指向aws-eb:prodNPM_USE_PRODUCTION: false让平台安装全部依赖含 devDependencies因为生产构建webpack、babel 等都在构建期运行需要 devDependencies 中的构建工具链。多环境注意如果存在多个环境如 staging / production建议移除.ebextensions中的NodeCommand条目改为在每个环境的 Web 控制台手动配置Configuration Software Node command以避免各环境共用同一命令配置。第 3 步创建.npmrc文件# 详见 react-boilerplate issue #2566 unsafe-permtrue说明部分 npm 生命周期脚本如 postinstall在以 root 用户运行时可能因权限问题被跳过unsafe-permtrue允许 npm 以当前用户而非降权后的 nobody执行脚本确保依赖安装阶段的生命周期钩子正常执行。第 4 步提交改动并通过 EB CLI 部署git add -A git commit -m Configure Elastic Beanstalk deployment eb deploy {target environment name}eb deploy会打包当前目录代码并上传到指定环境平台按.ebextensions配置执行构建与启动。部署方案对比与选择建议平台运行方式核心改动适用场景Heroku运行 Node 服务start:prod添加Procfile、设置 buildpack需要服务端能力API、SSR、快速起步的 PaaS 托管AWS S3纯静态托管构建./build并上传、开启静态网站托管纯前端 SPA、低成本静态托管可配合 CloudFront已有服务器子目录由 Apache/NGINX 托管静态文件修改 webpackpublicPath/BUILD_FOLDER_PATHhistory 加basename已有服务器、需要挂在既有域名子路径下AWS Elastic Beanstalk运行 Node 服务aws-eb:prod添加 npm script、.ebextensions、.npmrc需要 AWS 生态内可弹性伸缩的 Node 托管无论选择哪种方案底层都依赖两条链路npm run build产出的./build静态资源含 gzip 压缩包与离线缓存文件以及npm run start:prod启动的 Express 生产服务server/index.js addProdMiddlewares.js。理解这一点后遇到任何部署问题都可以回到构建产物与生产中间件两个层面排查。延伸阅读部署与服务器配置的相关背景可参考 docs/general/README.md其中列出 Deployment 为目前 Heroku AWS 相关的部署指南以及 docs/general/server-configs.md常用的开发/测试命令一览见 docs/general/commands.md。【免费下载链接】react-boilerplate A highly scalable, offline-first foundation with the best developer experience and a focus on performance and best practices.项目地址: https://gitcode.com/gh_mirrors/rea/react-boilerplate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考