「Windows 上 DSH 双击就崩,日志里一行 Unexpected token,肯定是安装包坏了,重装一遍吧。」 这句话里的两个判断都值得再核实:报错确实是 JSON 解析失败,但重装既不能帮你定位原因,还可能一并清掉原始证据。
原始讨论是 #10883,标题明确提到 0.2.1-rc.3 在 Windows 上启动失败,且清单带有 U+FEFF。发帖人附上了崩溃报告压缩包,并称重新安装没有解决问题。这里先划清两条边界:可见正文没有完整展示压缩包内容,因此不能独立证明所有启动失败都由此引起;讨论已关闭但没有回答,关闭状态不代表问题已经修复。
排查时常见的六类误判:
- 把某个文件解析失败当成整个安装损坏;
- 看到报错发生在启动阶段,就认定是主程序 bug;
- 把重新安装无效理解成任何安装问题都不该重装;
- 把修好后能启动当成所有配置和功能都正确;
- 认为 profile 下所有 JSON 文件都有同样的问题;
- 把讨论里的代码修改建议当成已经发布的修复。
先记住这一点:BOM 只是一个候选原因,不能解释所有 Unexpected token。 站内基础版可参考 Windows 上 profile 清单带 BOM 导致启动失败。
一、报告到底说了什么
原文提供的证据不多,值得逐条拆开来看。
发帖人报告了三件事:Windows 上 0.2.1-rc.3 启动失败;崩溃报告压缩包显示清单开头有 U+FEFF;重新安装没有解决问题。这些都属于观察。
一位参与者回复说,profile resolver 中有多处代码会将 package.json 按 UTF-8 读入后直接交给 JSON.parse,没有剥离开头的 BOM;因此,以 ` 开头的字符串会抛出Unexpected token`,并建议在解析前移除该字符。这些内容来自源码阅读和修改建议,不是官方发布的修复说明。
这两类信息不能混为一谈:前者描述现象,后者尝试解释机理。若直接概括成「这是个已知 bug,删掉 BOM 就好」,就把尚未验证的假设说成了结论。
一张证据对照表
| 证据 | 可能说明 | 不能单独证明 |
|---|---|---|
| 启动时出现 JSON 解析错误 | 某个文件在该路径无法解析 | 首字符必定是 BOM |
指定清单开头有 U+FEFF |
可能遇到了报告所述的解析路径 | 已安装版本的实现一定相同 |
| 报告中重新安装无效 | 当时重新安装不足以解决问题 | 所有安装问题都不应重装 |
| 修改后启动成功 | 本次测试涉及的启动路径已通过 | 所有配置和功能都正确 |
阅读这张表时,第三列才是排查中需要补上的证据。前两列提供线索,第三列提醒你不要把线索当成结论。
二、为什么一个清单能挡住整个启动
CLI 参考说明,dsh <name> 会启动 $DSH_HOME/profiles/<name> 下的 profile。该 profile manifest 中的 dsh.profile.bundles 列表决定先应用哪些组合包补丁,之后才应用 profile、home 和命令行覆盖。
这个顺序解释了一个容易忽略的情况:profile 元数据是在应用就绪前读取的。因此,清单解析一旦失败,用户遇到的不是「某个插件没加载」,而是「整个应用起不来」——一个几 KB 的元数据文件,拦住了后续所有功能。
所以,「启动崩了」本身并不能提供太多信息。这个说法可能指向下面几种完全不同的问题:
- 某个 JSON 文件在特定路径下无法解析;
- 文件无法访问或权限不足;
- 模块解析失败;
- schema 验证不通过;
- 插件启动阶段抛错。
CLI 参考说明,这些启动错误都会被报告,程序也会以非零状态退出;但它没有说 JSON 错误一定由 BOM 造成。排查时要守住这条线:JSON 解析错误只能证明「有个地方在把文本解释成 JSON 时失败了」,不能证明失败原因是什么。
BOM 在这里扮演什么角色
BOM(Byte Order Mark)是可能出现在文本开头的编码标记。讨论参与者指出,在报告涉及的代码路径中,它会成为 JSON 内容前面的多余字符——解析器看到 {"name":...},第一个 token 就不是合法 JSON。
关键不在于 BOM 的定义,而在于这条链上的三个条件必须同时成立:
- 文件确实以
U+FEFF开头; - 已安装版本的对应读取路径确实没有剥离它;
- 你的启动过程确实走到了这条路径。
只要其中一个条件不成立,「删掉 BOM 就好」就可能无效。所以下面的检查并非走过场,而是要逐项核实这些条件。
三、动手改之前先验什么
按这个顺序检查,每一步只回答一个问题。
第一步,固定现场。 记录已安装版本、完整错误文本,以及诊断信息中明确指出的文件。分享报告前,先检查其中是否包含敏感信息——崩溃报告和 profile 路径里常会带有用户名、目录结构,甚至凭据片段。
第二步,分清是哪个清单。 确认当前选中的是哪个 profile,再判断出错的是该 profile 的 manifest,还是其他包清单。讨论参与者提到 resolver 中有多处读取路径,因此不能认定 profile 目录下所有 JSON 文件都有问题,更不要顺手批量重写。
第三步,看字节。 用可信的编辑器或字节查看器打开诊断指明的文件,确认编码和前导标记。这一步应当得到「开头是/不是 EF BB BF」这样可复核的事实,而不是「看起来像有问题」。
第四步,留副本再动。 修改前先制作可恢复的副本。如果文件由用户管理,而且确认开头确有 BOM,就用支持无 BOM UTF-8 的编辑器另存一份内容相同的 JSON。只处理编码,不改动内容——排查编码时顺手修改配置字段,是最常见也代价最高的错误。
第五步,同法重启并留痕。 用相同方式重新启动并记录结果。如果仍然失败,保留新诊断,与原错误逐项比较:BOM 可能只是伴随现象,底下也可能还存在第二个错误。
这五步属于调查流程,不保证重写文件就能解决原报告中的问题。所引讨论没有提供经过验证的最终用户编辑流程,也没有展示这项操作在原始压缩包所涉环境中的效果——这一点必须说明,以免读者以为照做就一定能修好。
一个容易漏掉的前提
如果文件由安装器或其他工具管理,编辑前要先弄清它是如何生成的。否则,工具下次运行时可能会把原来的字节重新写回来,形成「改了、好了、过几天又坏了」的循环;人很容易把它误读成「问题没修好」。
如果文件归属不清楚,正确做法是联系相应的维护或支持渠道,而不是自己猜。
四、为什么不该一上来就重置 profile
这件事值得单独说明,因为它很容易变成耗时的折腾。
Profile 不是空壳,里面可能有已安装依赖和用户自己的补丁。CLI 将 --from-default-profile 描述为替换自定义目标的操作:先暂存一份全新的模板副本,替换成功时删除旧目标目录,包括已安装依赖和用户补丁。
换句话说,重置 profile 并非「无副作用的编码检查」,而是会同时改变多个变量的重写操作。参考文档确实解释了替换失败时如何恢复,但成功重置会在后续启动失败之前改变目标内容——也就是说,最需要保留原始状态时,它可能已经被改掉了。
再看它能带来的信息。重新安装或重置会同时改变版本、依赖、配置、清单编码等多个因素。即使之后能启动,也很难判断究竟是哪一项起了作用;如果仍然无法启动,原先可供对照的基线也没了,只能从头排查。
因此,建议按这个顺序来:先确认具体文件、先比对开头字节、先保留原件,再考虑重写。 把每一项有意的修改都记录下来,才能控制变量。
五、做对比实验时要注意什么
用干净 profile 做对照有帮助,但结论有明确边界。
干净 profile 能启动,只能说明「这套组合和用户数据下能启动」,不能证明原清单已经修复——因为干净环境的组合、依赖和用户数据都不同。这是有用的线索,还不是结论。
要让对比结果更有说服力,尽量做到:
- 保持 profile、启动方式和其他配置一致;
- 记录唯一改变的是哪个文件的编码;
- 如果同时替换了 profile、升级了版本、改写了多个清单,那么即使成功也无法判断原因。
反过来,如果检查发现根本没有前导标记,就说明这条假设不成立。此时应回到日志,继续排查其他解析或启动问题,不要为了印证报告而改写原本正常的文件。
改完还要再验一次内容
即使确认并移除了标记,也要检查文件内容是否被编辑器顺手改动。Manifest 记录包元数据,其中的 dsh.profile.bundles 列表直接决定哪些补丁会被应用。把排查范围限定在「确认过的文件和编码」上,是保住原有 bundle 列表最简单的办法。
重新启动后,除了确认能否进入界面,也要留意是否出现新的错误信息。一次启动成功不能代替后续功能验证;有些组合包问题要等到触发具体功能时才会暴露。
如果诊断指的是另一个文件
那就单独判断该文件的用途和归属。报告列出了多处清单读取路径,但没有证明这些路径都参与了这次启动。批量重写所有清单,既无法确认问题原因,也可能改动无关的包元数据——每个文件都要单独核实。
六、限制与安全边界
该报告针对一个特定候选版本,相关解释来自一位参与者的源码阅读。它不保证当前修复版本的状态,不代表所有 Windows 启动都会失败,也不能证明每个 Unexpected token 都由 BOM 引起。应以已安装版本的诊断输出和发布说明为准;不要只凭一份讨论就修改源码或无关的包清单。
安全方面有两点需要单独留意:
- 崩溃报告、路径和 profile 文件可能暴露个人信息或凭据。 CLI 明确提醒,原始插件错误可能包含敏感值,而且不会自动脱敏,所以分享前必须自行检查。
- 修改 manifest 会影响 profile 依赖及组合包。 保留原内容、留好恢复副本,并验证修改后的实际行为,这几件事都要做到。
最后还要记住:成功启动不等于环境安全,也不等于配置正确。 这个流程只处理「能不能起来」,不处理「起来之后连的是哪个端点、用的是哪把密钥」。
七、术语速查
- BOM:字节顺序标记;本文讨论的是开头的
U+FEFF。 - Manifest:解析 profile 或包时读取的包元数据。
- Profile:有名字的组合包与用户配置的组合。
- JSON 解析错误:无法将文本解释为 JSON,具体原因需要进一步检查。
- 候选版本:特定预发布构建,其行为不能推广到所有版本。
相关阅读
- Windows 上 profile 清单带 BOM 导致启动失败
- 启动失败时完整诊断日志在哪里
- 把启动诊断信息脱敏再分享
- 升级后 overrides 被跳过怎么查
- 新建一个缺失的自定义 profile
- 更多 DSH 实践文章
本文依据 DeepSeek Harness CLI 参考与社区讨论 #10883 整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
原文地址:https://dsh-plugin.com/zh/blog/windows-profile-manifest-bom
插件与文档收录于:https://dsh-plugin.com/zh/blog