后期维护和排查效率记录

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

记录 1：中文乱码会直接影响排查效率

现在用终端看部分源码时，中文注释和提示文案会显示乱码。浏览器里不一定有问题，但对维护影响很大，因为很多注释本来就是为了解释业务规则。

这个问题后面需要单独处理，不能边改业务边顺手改。原因是编码问题牵涉文件很多，如果和业务改动混在一起，代码 review 时很难判断哪些是功能变化，哪些只是编码修复。

比较稳的处理方式：

• 单独开一次编码清理。
• 先确认文件实际编码。
• 统一保存为 UTF-8。
• 只处理注释和文案，不改逻辑。
• 清理后跑一次构建。

记录 2：公共组件改动要先列受影响页面

表格、弹窗、抽屉、上传、Excel 这些组件被很多模块使用。独立开发时有个坏习惯：当前页面需要什么，就直接在公共组件里加。短期很快，长期容易影响其他页面。

现在改公共组件前，我会先列三件事：

• 哪些页面正在使用这个能力。
• 新增逻辑默认是否关闭。
• 有没有办法通过 props 控制，而不是改默认行为。

比如表格的 tooltip、金额大写、拖拽排序、表头配置，都应该尽量做到默认不破坏老页面。

记录 3：接口错误统一吞掉以后，页面要自己判断空值

request.js 里响应错误最后返回的是 Promise.resolve(err.response.data)，这能避免页面大量 try/catch，但也带来一个问题：页面拿到的 res 不一定是成功结构。

所以业务页面里不能默认 res.data 一定存在。尤其是列表页、详情页、保存后刷新这类逻辑，要判断 res.code === 0 再继续。

这个问题容易导致二次错误：真正的接口错误已经被 message 提示了，但页面继续读 res.data.xxx，又抛出前端异常，反而干扰排查。

记录 4：空字符串转 null 是好用但要小心的全局规则

请求拦截器里会把 req.data 中的空字符串转成 null。这个规则对很多查询和表单提交有帮助，因为后端通常更喜欢 null。

但它也有副作用：如果某个字段业务上就是允许空字符串，前端会在提交前把它改掉。以后遇到“我明明传了空字符串，后端收到 null”的问题，要先想到请求拦截器。

这类全局规则最好在接口文档或项目约定里明确写出来。

记录 5：git log 里的大量 bugfix 说明需要补记录

最近提交记录里很多都是 bugfix，还有一些针对同一业务连续修复。这说明当时为了赶进度，问题解决了，但原因没有留下来。

以后至少要在本地笔记里补三类信息：

• 这个 bug 的触发条件。
• 具体原因是数据、权限、组件还是环境。
• 最终改了哪里，为什么这样改。

不一定每个 bug 都写成长文，但要能让一个月后的自己快速恢复上下文。

记录 6：独立开发也需要发布检查清单

一个人开发时最容易省掉流程，但项目复杂以后，清单反而能省时间。现在这个项目每次发版前至少应该检查：

• 登录、菜单、权限是否正常。
• 合同、项目、费用、薪资这类核心列表能否打开。
• 薪资表格是否能加载、编辑、计算。
• 大屏和地图是否正常显示。
• 文件上传、预览、导出是否正常。
• 构建产物是否生成，压缩包是否是最新。

这些检查不复杂，但可以挡住很多低级问题。