离线开发环境排查清单：症状分流、本地进度与交付核验

排查开发环境启动问题时，整页空白和工作区目录为空看起来都像“还没准备好”，处理路径却并不相同。把分层思路写成文章，适合讲一次具体观察；若要反复勾选、保存进度并留下可复查记录，纯文档就不够用了。于是做了一个纯前端、可离线打开的勾选清单：解压后双击 index.html 即可使用，不必安装依赖、启动本地服务器，也不必注册登录。

源码在 GitCode 仓库 dev-startup-checklist。2026 年 11 月 12 日（北京时间）已把作品提交到开发者作品展览馆，页面为 开发环境启动排查清单（本地离线）。本文只讨论设计取舍与交付核验，不把上架页状态写成官方审核结论。

一、先按症状分流，而不是给一套通用命令

核心数据与纯函数放在 checklist-core.js 里，不依赖页面元素，也不发起网络请求。症状固定为三类：整页空白、工作区目录为空、资源加载慢。每类各五步，允许多选；多选时按症状分区展示，不会把两套步骤捏成一条流水线。

必须写进数据里的约束是：「自行 clone / 自行获取代码」不能出现在整页空白的步骤标题中。空白页往往还看不到工作区，这时提示去拉取代码，既可能方向错了，也可能把终端操作当成万能修复。获取代码只出现在「工作区目录为空」流程，并且排在「核对权限与目标目录安全性」之后。单测会检查这两点：空白流程的标题和说明里不含「自行 clone」；空目录流程里，确认权限的步骤序号小于获取代码的步骤。

每一步只能标记为「待验证」「已检查」或「不适用」。「已检查」只表示已经看过该建议，不等于问题已经解决。页面顶部也写明：这不是自动诊断，也不是任何云平台的官方工具。

二、进度放在本机，导出必须先预览

页面交互在 app.js。勾选症状、修改步骤状态，以及最长 2000 字的备注，会写入当前浏览器的 localStorage，键名为 dev-startup-checklist-v1。同一浏览器可以恢复上次进度，也可以重置当前勾选，或清除本机保存。若浏览器禁止本地存储，页面会提示无法写入，但当前会话仍可继续勾选。换浏览器、换设备或清除站点数据后，进度不会自动出现在别处。

读入本地数据时，normalizeState 会丢掉未知症状字段，并把非法状态值改回「待验证」，避免损坏的 JSON 把界面带进未定义状态。解析失败则回到空进度，而不是中断页面。

需要留存记录时，可以先预览，再下载 startup-checklist-record.md。导出内容只包括导出时间、本地进度更新时间、所选症状、各步状态、用户手写备注，以及“不是自动诊断报告”等声明。导出逻辑不会采集 Cookie、HAR，也不会写入 navigator.userAgent 这类环境指纹。但工具并不会自动检查备注是否含有秘密：若自行写入敏感信息，导出文件会原样带出，分享前必须再看一遍。

三、目录保持扁平，正因为要离线打开

仓库源码结构如下，没有构建步骤，也没有第三方前端依赖：

dev-startup-checklist/
  index.html
  styles.css
  checklist-core.js
  app.js
  test-core.js
  README.md
  GALLERY_INTRO.md

index.html 只引入同目录的样式和两份脚本。样式文件中没有外部字体或 CDN 地址；源码中也没有 fetch、XMLHttpRequest 或远程脚本引用。页面不读取剪贴板，不访问本机其他文件，也不解析日志。关闭页面后，除主动保存在本地存储中的勾选进度外，没有云端副本。

四、测试范围要写清楚，不能把单测当成界面验收

test-core.js 只在 Node.js 里验证核心逻辑，不启动浏览器，也不参与页面运行。覆盖范围包括：三类症状与步骤是否完整、多选是否分区、空白流程是否排除 clone、空目录中获取代码的顺序、非法状态如何规范化、进度如何统计、导出声明与内容边界，以及对损坏 JSON 的容忍。交付说明要求执行语法检查和该单测；本次在 Node.js v24 下重新执行，7 项全部通过。

尚未用图形界面浏览器做视觉回归。布局是否可读、点击是否符合预期，以及 localStorage 在真实浏览器中的读写，仍需打开 index.html 另行复核。单测通过，不能写成“已在各浏览器验证可用”。

五、详情包也要对齐：正文路径必须等于压缩包成员

源码包和作品详情包不是同一件事。详情包给展览馆说明页使用。最终压缩包内只有两个成员：README.md 和 resources/architecture.png。正文用相对路径引用架构图：

![系统架构图](resources/architecture.png)

如果图片在 resources/ 下，正文却写成根目录的 architecture.png，别人解压后就会看不到图。整理过程中确实出现过“图放在根目录”和“图放在 resources 目录”两种草案，最终以正文引用路径与压缩包成员完全一致为准。本地还核验了：详情说明与打包文本一致、架构图校验和一致、压缩包 CRC 正常、正文不含本机绝对路径、体积远小于常见的 20 MiB 上限。这些只是本地自检，不是平台官方门禁脚本的结论，也不能据此声称已经审核通过。

仓库地址使用 HTTPS 并以 .git 结尾，分支为 main。作品按本地文件打开设计，在线体验地址保持空白。

六、适用边界

这个清单能做的，是把不同症状的建议分开，并留下可复查的人工勾选记录。它不能定位服务端根因，不能修复环境，也不能保证某一次启动问题一定能解决。本文也不是对某次具体故障的归因，更不是积分或登录状态的核验说明。若现场证据不足，应明确标记“根因未确认”，而不是把清单勾选结果当成诊断报告。