在现代云原生架构的交付过程中，前端与后端的解耦部署往往伴随着各种路由匹配、跨域以及字库缺失的隐形巨坑。本文将真实复盘本站前端升级过程中遭遇的 Nginx 配置文件大卡死、404 路由丢失 以及 PDF 导出中文乱码 的完整解决链路。
一、 约定大于配置：为什么我们拔掉了 .env 环境变量文件？
在传统的前端部署中，我们习惯于在 .env.production 中硬编码后端的绝对请求地址（例如带有具体的端口号）。然而，这种做法在容器化环境中暴露了巨大的弊端：一旦服务器 IP 变更或端口调整，就必须重新修改源码、重新打包，且极易引发浏览器的跨域拦截（CORS）。
在本次重构中，我们采用了更高级的 “前端默认相对路径 + 网关动态反向代理” 组合拳：
前端纯净化： 彻底移除所有环境配置文件。现代前端脚手架（如 Vite）在无配置时，会默认向当前域名发起相对路径请求。这意味着无论前端镜像被推送到哪个环境，它都能完美自适应，无需二次打包。
网关内网带路： 所有的跨域和路由分发压力，全部交由处于边缘位置的 Nginx 统一消化。
二、 核心狙击点：Nginx 灵魂配置的艺术
前端由于使用了相对路径，发出的接口请求形如 /api/chat。为此，我们在 Nginx 的核心配置文件中嵌入了以下至关重要的代理规则，直接终结了跨域与路由 404 问题：
location /api/ { proxy_pass http://wiselink-server:8081; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering off; proxy_cache off; }
关于这段配置的致命技术细节：
末尾斜杠的魔鬼细节： 注意
proxy_pass末尾的8081后面千万不能加斜杠。如果加了斜杠，Nginx 会在转发时悄悄剥离掉/api前缀，导致后端 Java (Tomcat) 找不到匹配的 Controller 路径，从而疯狂抛出 404 错误。不加斜杠，则是原封不动的完整路由转发。流式打字机开关： 显式关闭了
proxy_buffering和proxy_cache。这是大模型 AI 智能体（Agent）流式输出（SSE/Stream）所必需的，否则 Nginx 会把 AI 的响应憋到一口气吐出，失去打字机的丝滑效果。
三、 突发险情：5MB “乱码巨兽” 卡死事件复盘
在持续构建过程中，由于某次无缓存编译指令的路径错位，导致大体积的二进制前端静态文件（或字体碎屑）被误重定向灌入了 nginx.conf 文本中。原本仅有十几行的配置文件瞬间膨胀至 5.17 MB 的巨无霸。
Nginx 引擎在启动时试图去解析这堆庞大的二进制乱码，直接导致容器疯狂闪退、系统卡死。
解决方案： 面对这类突发污染，无需肉眼排查。直接利用 Linux 的
cat << 'EOF'清空并强行覆写标准配置，随后通过docker compose build --no-cache彻底清洗构建缓存，让前端原地满血复活。
四、 尾声绝杀：PDF 导出中文字库的最后一公里
当前后端网络彻底咬合后，测试 PDF 导出报告时，Java 后端再次抛出 Notice: No suitable CJK font was found... 的警告，导致生成的 PDF 报告中文全部显示为空白或乱码。
隔离的孤岛： 根本原因在于 Docker 基础镜像（如 OpenJDK 极简版）为了追求极致体积，内部是全裸的，并未预装任何中文字体。
最高指挥权通道： 我们通过 Docker Volume 将宿主机的文泉驿微米黑字体（wqy-microhei.ttc）挂载进容器内部，并通过环境变量进行 GPS 级的精准导航。
TTC 的索引陷阱： 在配置 Java 环境变量时，由于目标是
.ttc（字体集合文件），必须在路径末尾精准补上,0。只有这样，底层的 Java 字体解析引擎才能顺利摸到集合中的第一个字库索引，否则判定失效会直接触发代码的异常跳过。
五、 持续迭代：标准生产流水线（CI/CD）
历经此役，本站的全栈部署彻底演进为标准的商业级方案。未来的前端新功能迭代，将享受到极简的“丝滑三步走”，在不打断用户当前访问的前提下，完成无缝的后台升级替换：
代码对齐：
git pull（拉取纯净业务源码，增量覆盖，告别手动清空）。静默编译：
docker compose build wiselink-web（在后台悄悄编译全新的 Nginx 前端镜像）。瞬间接管：
docker compose up -d wiselink-web（旧容器闪击下线，新容器瞬间顶上，用户几乎毫无感知）。
云原生底座下的每一次探索，都是在用确定性的架构逻辑，去驯服那些不确定性的配置魔鬼。至此，全栈大通车，终极大捷！