我把写作专家团做成安装包,却被一个看不见的字符卡了3天

功能是你自己的，跑起来才是别人的。

周末晚上，朋友发来一条消息：“你那个写作工具，我装好了，但打开是空的。”

我心里一沉。功能是我亲手写的，本机跑得好好的，选题、写稿、审稿，每一步都正常。怎么一到别人机器上，就变成白屏了？

我让他截图。他发来一张「我的专家」界面——一整面灰底，本该列着选题专家、写作专家、审稿专家的地方，全是白的。

最难受的不是它坏了，是它坏得毫无声息。没有报错弹窗，没有提示信息，连个“加载失败”都不给。就像一扇门锁坏了，但你转钥匙的时候，它连“咔哒”一声都没有。

那时候我还不知道，这场排查会折腾我一整天多。而我最后找到的”凶手”，跟代码逻辑一点关系都没有——是文件开头3个看不见的字符。

翻车之后，我自己完全摸不着头脑——我不懂技术，功能有没有问题，我看不出来。幸好我搭这套工具，一直有个 AI 搭档帮我干活。我把朋友的报错一股脑丢给它：“装上之后是空的，没有报错，帮我查。”

AI 先查功能逻辑，回我：本地跑一遍全通，代码没毛病。

再查安装路径：文件没复制全？版本放错了？对了一遍，该在的都在。

又查环境依赖：是不是别人机器上少了什么？重装两次，还是白屏。

折腾了整整一天多，AI 把能想到的都查遍了，最后把疑点锁定在一个文件上——WorkBuddy 加载「我的专家」时读的那个本地注册文件，marketplace.json。它让我把朋友机器上这个文件要过来。

文件发过来，AI 对着逐行看，突然说：“文件开头，有几个看起来是空格的东西。”

不是空格，是3个看不见的字符，藏在文件最开头。

就这？就这3个东西，折腾了我一天多？

AI 把它们删掉，重新保存，让朋友再打开一次。工具，出现了。那一刻我对着屏幕愣了很久。不是气自己蠢，是气这种错误太隐蔽——它不报错，不提醒，不给你任何线索。如果你不知道“字符还能藏在文件开头”，你可能永远找不到它。

后来我才知道，这3个看不见的字符，是同一个东西——一个叫 BOM 的标记。

BOM 是“字节顺序标记”，一个看不见的字符，在 UTF-8 编码下占 3 个字节。所以你看到的“3个空格”，其实是它。它平时看不见，但程序读文件时，是能“读到”它的。

那问题来了：这个 BOM 是哪来的？答案不在我写的功能里，在我写的安装脚本里。早期版本的安装器，用 PowerShell 5.1 的 Set-Content -Encoding UTF8 去写这个本地注册文件——而这行命令有个隐藏副作用：它会在文件开头自动加一个 BOM。

为什么我本机一直正常？因为本机的 marketplace.json 是AI直接写的，不是通过脚本，不带 BOM。朋友机器上的那个，是安装器自动生成的——悄悄被加了 BOM。所以同一套工具，我这边跑得好好的，一到别人机器上就白屏。

这解释了一个我绕了很久的弯：问题根本不在脚本逻辑里，代码没问题，是写文件的方式带了毒。

为什么连报错都没有？因为 WorkBuddy 读这个文件用的是 JSON.parse，一读到文件开头的 BOM 就抛 Unexpected token。程序外面包了一层“自动修复”逻辑，但这个兜底只修文件里多余的逗号，不处理文件开头的 BOM。于是修复失败，整个列表被当成“没有数据”处理，就变成了白屏。

最坑的是：它一旦失败就返回空列表，而且不会自动重试——重启也没用，除非手动去掉 BOM。所以你不会看到任何错误，只会看到“我的专家”里干干净净——什么都没有。

修复其实只有一步：写文件时，用不带 BOM 的方式写。

回头看，这次排查真正教会我的，是两件事。

第一，会报错的 bug 是好朋友，它告诉你在哪；不报错的问题才是杀手，它让你怀疑人生。排查的时候，别只盯着报错——没有报错本身，就是一条线索。

第二，工具链的“默认值”往往藏着坑。我用的那个命令，它默认加 BOM，是因为作者觉得“大多数情况这样安全”。但安全的前提，是读你文件的程序不挑剔。一旦对面是严格解析，默认值就成了炸弹。

我在那一天多里，用最疼的方式学会了“默认”两个字不能全信。

这套写作工具现在能免费领，私信我【写作】。如果你也想把自己搭的工具打包给别人用，这个坑，提前帮你避了。

如果你觉得今天这篇有收获，点个赞、在看、转发三连，我们下篇见。

THANKS FOR READING