024. 前端打包与 Nginx 子路径部署

学习目标

这一节把前端项目部署到服务器上，并通过 Nginx 子路径代理解决跨域和静态资源访问问题。

学完后，你应该能理解：

• 后端端口为什么要在云服务器防火墙里放开；
• 前端部署为什么不直接访问后端端口；
• 子路径代理如何减少跨域问题；
• .env.production 为什么要换成服务器地址；
• React 项目打包后为什么不能直接打开 HTML；
• build 目录应该如何上传到服务器；
• 导出图片或 PDF 时为什么要关注图片跨域。

放开后端端口

后端服务跑起来后，需要确认服务器防火墙放开对应端口。

否则本地或 Nginx 都可能访问不到后端。

这里要区分两层防火墙：

• 云厂商控制台的安全组；
• 服务器系统或宝塔面板里的防火墙。

如果后端服务监听了某个端口，就要确保这个端口在需要访问的范围内可用。

学习阶段可以先按课程配置放开对应端口；生产环境不要随便把后端端口直接暴露给公网。

为什么要用子路径代理

前端页面和后端接口如果是不同域名、不同端口，就会遇到跨域问题。

项目里除了普通接口请求，还会导出简历图片或 PDF。导出时会用到前端截图相关能力，例如 canvas。

canvas 下载图片时对跨域更敏感。

如果图片、接口、页面来源不一致，就可能出现：

• 页面能显示图片；
• 但导出图片失败；
• 或者 canvas 被浏览器标记为不安全；
• 最终 PDF 或图片导出异常。

所以这里继续使用 Nginx 子路径代理，把接口和资源访问收敛到同一个站点路径下。

Nginx 配置思路

静态站点里需要增加几个转发规则。

大致思路是：

路径	转发目标
前端访问路径	服务器上的前端静态资源目录
后端接口子路径	后端服务端口
简短入口路径	重定向到前端主路径

这样用户访问的是同一个域名下的不同路径，而不是直接访问后端端口。

这和前面部署完整实战项目时的思路一致：前端页面走静态资源，接口请求走反向代理。

修改生产环境变量

前端打包前，要检查 .env.production。

里面的地址要换成自己的服务器地址，并且优先使用 Nginx 子路径代理后的地址，而不是直接写后端端口。

例如要关注：

• 接口基础地址；
• 文件上传地址；
• 静态资源前缀；
• 是否启用 mock。

生产环境打包时读取的是生产环境变量。这里配置错了，打包出来的静态文件也会请求错误地址。

打包前端

前端项目打包后，会生成 build 目录。

打包过程中如果开启了包分析插件，可能会启动一个临时端口显示构建分析结果。这个只是辅助查看打包内容，不是线上部署入口。

真正要上传的是 build 目录里的静态文件。

注意：不要直接双击打开 build 里的 HTML。

React 单页应用需要通过 Web 服务访问，直接打开本地 HTML 时，资源路径和路由路径很容易不对。

上传静态资源

服务器上需要准备一个前端部署目录。

把 build 目录里的文件上传进去，让 Nginx 的静态资源路径指向这个目录。

上传后访问配置好的前端路径，应该能看到登录页或需要登录的页面状态。

如果看到空白或资源 404，优先检查：

• Nginx 静态目录是否正确；
• 前端 base path 是否正确；
• .env.production 地址是否正确；
• 上传文件是否完整；
• 浏览器控制台是否有资源加载错误。

登录接口仍可能是 mock

这一节部署的是当前前端阶段。

如果后端登录接口还没有完全接好，页面登录可能仍然使用前端 mock 接口。

这不影响静态部署验证。

部署验证先看：

• 页面能不能打开；
• 静态资源能不能加载；
• 前端路由能不能访问；
• 接口地址有没有指到正确路径；
• 后续接真实后端时是否能顺利替换。

图片需要重新保存

简历页面里有些图片可能还是旧地址。

如果图片地址没有更新，线上导出时可能显示异常。

解决方式是进入对应详情，保存一次，让系统重新上传或重新生成图片地址。

保存后再看图片路径，应该会变成新的资源地址。

如果每个模板或每份简历都引用了旧图，就需要逐个打开保存。

图片留白和根节点宽度

有些导出的图片左右会留白，不一定是部署问题。

可能是前端样式里根节点宽度没有固定，导致截图区域没有撑满。

这时要检查模板根节点样式，给它明确宽度，让截图时能按预期铺满。

所以图片导出问题要分两类看：

• 图片资源加载不到：优先看路径和跨域；
• 图片布局不对：优先看模板样式。

当前部署的特点

这个前端项目部署难度不高，因为数据库和基础后端环境已经准备过。

这一节主要练的是前端上线闭环：

• 放开后端端口；
• 配 Nginx 代理；
• 改生产环境变量；
• 打包前端；
• 上传静态资源；
• 访问线上路径；
• 修正图片资源和样式问题。

后面项目复杂起来时，仍然会反复用到这套部署思路。