前端部署后图片集体裂开？我们踩了Git跨平台构建的隐性坑

上周三上线后运维群炸了：某核心功能页的产品图全成破损图标，用户压根看不了内容。开发同学拉了最新代码本地验证，开发环境、测试环境都正常，部署的也是刚构建的最新前端产物，Nginx 返回 200，可 curl 直接拉图片，拿回来的却是损坏的 PNG 数据——这就有点没头绪了。

我先把 Windows 和 macOS 两个构建环境的同版本 dist 产物拉来，给所有图片资源算了 MD5。结果同一套源码，Windows 构建出的 PNG 哈希值和 macOS 的完全对不上，而且 Windows 版图片文件普遍比 macOS 大 10~20 字节。顺着这条线查 Git 配置，发现 Windows 开发机的 core.autocrlf 是 true，macOS 上是默认的 input；再看项目 .gitattributes，压根没给图片格式做二进制声明，Git 把所有没声明的文件都当文本处理，在 Windows 下把 LF 换行符转成了 CRLF。我又核了下 Nginx 响应头，传输环节没做额外编码转换，问题确实出在构建产物这一环。

core.autocrlf 是 Git 为解决 Windows 和 Unix 换行不一致设计的：默认开 true 时，提交自动把文本 LF 转成 Windows 要的 CRLF，checkout 再转回来。但它对所有没声明为二进制的文件都生效。PNG/JPG 这类图片的二进制数据里本来就有大量 0x0A（LF）字节，被无差别一转，文件结构直接坏掉，自然加载不出来。macOS 默认不开启全量文本转换，core.autocrlf 是 input 模式（只提交时转 LF，checkout 不转），所以构建出的图片完好，这也是本地开发环境看不出问题的原因。

修起来分三层：第一，配置层，统一所有开发机的 Git 设置，Windows 机把 core.autocrlf 改成 false，别再无差别转换二进制文件；第二，规则层，在项目根目录 .gitattributes 里明确把图片声明成二进制——*.png binary、*.jpg binary、*.gif binary、*.webp binary、*.svg binary，从源头堵住 Git 对图片的文本转换；第三，流程层，在构建里加一步产物一致性校验，不同平台构建后比对核心资源的哈希，不一致就直接卡住构建，不让异常资源上线。

这套排查正好对上我们团队落地的任务拆解方法论：先划问题边界（D1），再定位根因（D2），设计组合方案（D3），验证后上线（D4），最后把步骤和方案沉淀成内部排查手册（D5），从发现到落地不到 4 小时，没反复试错。

这种坑最磨人的地方是本地永远复现不出来——开发机和测试环境都正常，只能等线上炸了才暴露。所以跨平台前端项目别等出事再补 .gitattributes，从第一天就把二进制资源声明钉死、把产物一致性校验加进构建，比事后救火划算得多。