本地环境、接口地址和构建记录

本文是「bylcloud-web 开发问题记录」系列之一。bylcloud-web 是基于 Vue 3 + Vite + Element Plus 的企业后台系统，笔记按「现象、排查、处理、下次注意」记录开发中真实遇到的问题。

记录 1：本地接口到底连哪套环境

有一段时间本地调接口经常出现“刚刚还可以，刷新后接口又不对”的情况。后来发现不是后端服务不稳定，而是项目里接口地址有两处容易混淆。

一处是 vite.config.js 里的 dev proxy。开发时 /api 会转发到 devProxy.api，当时里面保留了测试网关、本地 IP、内网测试机、生产环境等多套地址。另一处是 src/utils/urlConfig.js，这里又根据 import.meta.env.MODE 返回 apiBase、webUrl、goviewUrl、OSS bucket、文件预览地址等。

当时容易犯的错是：我只改了 urlConfig.js，但实际开发请求走的是 Vite proxy；或者只改了 proxy，页面里某些直接用 url.apiBase 的逻辑还是旧地址。最后的处理方式是每次切环境先确认两件事：

当前请求是不是以 /api 开头，是否被 Vite proxy 接管。
当前模块有没有直接读取 urlConfig.js 里的 apiBase 或其他地址。

这个问题不复杂，但很耗时间。尤其是接口返回结构一样时，不容易马上发现自己连错环境。

记录 2：build-test 和 production 不能只看命令名

项目脚本里有 test:byl、build:byl，分别对应 vite build --mode build-test 和 vite build。我一开始会下意识觉得 test 就是测试环境，production 就是生产环境，但真正决定地址的是 urlConfig.js 里的 switch (import.meta.env.MODE)。

后来我给自己定了一个习惯：打包前先看 MODE 命中的配置，而不是只看命令名。特别是生产还有普通生产和另一个域名配置，不能靠记忆。

发版前检查项：

MODE 是否命中预期分支。
apiBase 是否是目标环境。
webUrl 是否和最终访问域名一致。
goviewUrl 这类子路径是否带了正确斜杠。
OSS bucket 是否是测试 bucket 或生产 bucket。

记录 3：dist.tar 打包只是最后一步，不代表构建成功

项目最后通过 compress.js 把 dist 压成 dist.tar。有一次我只看到压缩成功，就以为整体构建没问题。后来部署后才发现某个资源路径不对。

原因是压缩脚本只负责把已有的 dist 打包，它不验证里面资源是否完整，也不检查页面能否正常加载。所以后面我把顺序改成：

先完整跑构建。
看构建日志有没有 warning 或资源过大提示。
本地 preview 或用静态服务打开关键页面。
再执行压缩。

这一步对独立开发挺重要。因为一个人开发时，发版检查基本靠自己，如果把“打包成功”和“页面可用”混成一件事，很容易漏问题。

记录 4：依赖多以后不要随手升级

主应用里有 Element Plus、VXE、Univer、ECharts、xlsx、html2canvas、jspdf 等依赖。大屏部分还有自己的图表依赖。之前遇到过一种情况：升级一个看起来无关的包，结果样式或构建插件受影响。

后面我处理依赖会保守一点：

只为了解决明确问题才升级。
升级前看这个包是否影响全局入口。
升级后至少打开表格、弹窗、薪资表、地图或大屏这类重页面。
锁文件变动要单独看，不和业务代码混在一起提交。

独立项目不是不能升级，而是不能没有验证地升级。