三周开发 json-formatter 插件：在 WorkBuddy 攒 Credits 的实战复盘

标题起得有点中二，但事情是真实的：过去三周，我在 WorkBuddy 这个开发者工具平台上开发并上架了一个叫 json-formatter 的小插件，靠它攒下了一笔 Credits 点数。WorkBuddy 是一个面向开发者和效率党的第三方工具插件市场，平台提供固定的客户端底座，开发者按规范提交自己的功能插件，用户下载安装后日常调用。平台会根据安装量、活跃调用、用户评分综合出一个"质量因子"，按周期发放 Credits 点数，点数可以兑换平台 API 调用额度，也能换一些内置资源包。

我当时做这个插件的动机很简单：一是想搞明白 WorkBuddy 整个插件开发、审核、激励的闭环是怎么运转的，二是确实觉得平台自带的 JSON 预览框太素了，既不能排序也不能折叠，大一点的日志直接卡住。于是干脆自己写一个。现在插件上线三周，累计安装超过两百，周活跃调用稳定在三千多次，结余的 Credits 也到了三位数，虽然不算多，但整个链路跑通了，中间踩的坑也够写一篇文章了。这篇就按从选型、开发、上架到运营的完整顺序，把能复现的部分都摊开讲，给想在类似生态里做工具插件赚点数的同学当个参考。

1. 项目思路与方案选型

1.1 先搞明白 Credits 是怎么来的

做任何事情之前，先弄懂平台的激励逻辑。WorkBuddy 的 Credits 不是按"下载量 × 固定单价"这种简单公式发放的，它更接近一个带质量因子的复合算法。我自己的观测结果可以大致反推出一个关系：

单周期 Credits ≈ 安装量 × 权重 + 调用次数 × 权重 × 质量因子 + 评分影响

这个"质量因子"才是核心。平台喜欢的不只是"被装上"，而是"被持续使用"。一个插件如果用户装完后一周打开一次，和天天用来处理日志的，质量因子差距可能有两三倍。这意味着做插件不能只把功能堆上去，还得考虑用户会不会高频回来用。JSON 格式化这个场景天然优势就在这里——开发者的 JSON 处理几乎是日常操作，只要工具够顺手，唤起频率会很高。

另外 Credits 是周期性结算的，不是上架瞬间给你发一笔。这里有个很现实的策略：与其做一个大而全的工具一次性收割，不如做一个垂直场景的稳定工具，让 Credits 细水长流。平台生态里太多开发者一上来就想把所有功能揉进去，结果审核周期长、bug 多、质量因子被拉低，反而不划算。

1.2 为什么是 JSON 格式化

选这个方向我其实没有纠结太久。核心原因是三个：

需求频次高。调试接口、看日志、检查配置文件、处理数据导出，JSON 是现阶段最通用的数据交换格式之一，几乎每个后端、前端、测试、运维都躲不开。频率高意味着 Credits 的"调用次数"指标好拉。

边界清晰。一个格式化工具要做什么、不做什么，定义非常明确。它不像"笔记软件"或者"项目管理工具"那样动不动就需要账号系统、云同步、协同编辑，单独一个开发者完全可控。

现有的替代品都差点意思。平台内置了一个 JSON 预览器，但实测下来有几个硬伤：1MB 以上的文件打开会白屏，不支持 key 排序，折叠层级只能一展全展，错误提示只给一个 parse error 的 bug 图标，根本不知道错在哪一行。这些痛点就是我的切入点。

最终我给第一版定的功能清单是：格式化（可切换缩进）、压缩为单行、按 key 排序、层级折叠、语法错误定位、类型高亮、大文件防卡顿。看清楚，这里每一项目标都是从用户实际使用场景推下来的，没有一个是因为"别人有我也要有"。

1.3 插件形态与技术选型

WorkBuddy 的插件模型是"清单文件 + 前端入口 + 业务脚本"。清单文件用 JSON 描述插件元信息、权限声明和入口路径，前端入口负责界面渲染，业务脚本跑核心逻辑。整体类似浏览器扩展但不完全一样，它没有全域注入能力，只提供基于文本和 UI 的有限能力。

技术栈上我选了 TypeScript。原因很实际：核心逻辑涉及类型处理，JS 写起来很容易出现对数字、字符串和 null 的边界判断出错。TS 加一层类型保护，至少在编译期能拦住一部分低级失误。我自己这版在开发过程中就被 TS 拦过至少三次对Object.prototype.hasOwnProperty的误用问题。

依赖这块我刻意做到了"零运行时依赖"。JSON 格式化本身没有复杂的算法，原生JSON.parse加一个递归渲染函数就足够。不引第三方库有几个好处：打包体积小（整个插件压缩后不到 12KB）、面上给审核系统的好感也更好，而且后续更新不用做繁琐的依赖升级。

2. 环境搭建与核心功能设计

2.1 搭建开发环境与插件骨架

WorkBuddy 官方提供了一个命令行脚手架，我用的这个版本初始化命令是wb create-plugin。初始化完成后会自动生成一套标准目录：

json-formatter/ ├── manifest.json ├── src/ │ ├── index.ts # 入口，绑定 UI 事件 │ ├── core.ts # 格式化核心逻辑（纯函数） │ └── highlight.ts # 高亮渲染 ├── assets/ │ ├── icon.png │ └── screenshot-1.png └── README.md

manifest.json 是插件身份的凭证，我第一版的配置长这样：

{ "id": "dev.json-formatter", "name": "json-formatter", "version": "1.0.0", "description": "可排序、可折叠、可校验的 JSON 格式化工具", "permissions": [], "entry": "src/index.ts" }

注意permissions我直接留空数组。这是一个刻意的决定：格式化工具只处理文本内容，不需要读文件、不需要网络请求、不需要访问用户数据。权限声明越少，越不容易引起用户和审核的不信任。事实上在后续的审核反馈里，这个"零权限"反而成了最大卖点之一。

开发过程中 WorkBuddy 提供了本地调试模式，命令是wb dev。它会起一个本地调试器，实时加载插件目录，修改代码后热更新，和前端开发体验很像。日志面板能看到 console 输出，也能直接调用 manifest 配置的入口函数做单元验证。

2.2 格式化核心逻辑的设计思路

格式化逻辑我是这么拆解的：绝不基于字符串去美化。很多人第一次写格式化工具会用正则去补空格和换行，这绝对是个坑——正则在引号、嵌套、转义符面前会碎掉。正确做法是先JSON.parse把输入变成一棵真正的数据树，再在渲染阶段递归输出字符串。

数据树里的节点类型只有 7 种：对象、数组、字符串、数字、布尔、null、undefined（输入里不允许出现，但防御性要考虑）。每种类型的渲染规则我都单独处理。对象和数组是结构节点，负责组织缩进与换行；字符串走JSON.stringify保证转义正确；数字直接转字符串；布尔和 null 都是固定字面量。

这个设计还顺手解决了另一个问题：我希望支持 key 排序。排序发生在 parse 之后、渲染之前，直接对对象 key 做排序即可。如果是字符串正则方案，这一功能几乎做不出来。

解析错误处理是另一个重点。JSON.parse的报错信息虽然包含行列位置，但英文提示用户根本看不明白。我在插件里对 parse error 做了二次解析，把行列位置提取出来，再定位到具体输入行，用高亮标记出错误 token 附近的一小段上下文。这个功能的实现细节放到第 3 章细说。

2.3 界面交互与功能边界

界面布局我用的是三区结构：顶部工具栏、左侧输入区、右侧输出区。工具栏放四个核心动作：格式化、压缩、排序、清空。设置项放在一个折叠面板里，可以调整缩进宽度（2 空格 / 4 空格 / 制表符）、切换高亮主题。

这种布局没有太多创新，但胜在直觉。用户打开插件之后从输入到输出的路径只有一次点击，不需要学习成本。有一个细节值得讲：结果是实时预览还是点击按钮触发？我第一版做了实时预览，输入时防抖 300ms 自动格式化。后来在调试大文件的时候发现这会导致输入过程明显卡顿，改成了"输入与格式化完全分离，只有点按钮才触发"。这个改动直接优化了输入手感，也避免了对用户输入过程的干扰。

功能边界在第一版划得很死：只支持标准 JSON，不支持 JSON5、不支持 YAML 转 JSON、不支持 CSV 导入。这不是偷懒，而是把第一版的质量压在一个可控范围内。凡是涉及格式转换的功能都需要额外处理边界情况，这些扩展我会放到后面版本迭代，先把核心场景打磨到位。

3. 核心功能的完整实现

3.1 递归格式化函数是怎么写的

格式化核心我放在了src/core.ts，对外只暴露一个formatJson函数，接收原始字符串和配置项，返回格式化结果。实现核心如下：

// src/core.ts export interface FormatOptions { indent: string; // 缩进字符串：" " 或 "\t" sortKeys: boolean; // 是否对对象 key 排序 } export function formatJson(input: string, options: FormatOptions): string { const value = JSON.parse(input); return renderValue(value, 0, options); } function renderValue(value: unknown, depth: number, options: FormatOptions): string { const pad = options.indent.repeat(depth); const childPad = options.indent.repeat(depth + 1); if (value === null) return "null"; if (Array.isArray(value)) { if (value.length === 0) return "[]"; const items = value.map((item) => childPad + renderValue(item, depth + 1, options) ); return `[\n${items.join(",\n")}\n${pad}]`; } if (typeof value === "object") { const keys = Object.keys(value); if (keys.length === 0) return "{}"; if (options.sortKeys) keys.sort(); const entries = keys.map((key) => { const k = JSON.stringify(key); return ( childPad + k + ": " + renderValue((value as Record<string, unknown>)[key], depth + 1, options) ); }); return `{\n${entries.join(",\n")}\n${pad}}`; } if (typeof value === "string") return JSON.stringify(value); return String(value); }

这里有几个细节是踩过坑才加进去的。空数组和空对象必须返回紧凑形式，否则一个空的[]会被展开成三行，用户在大量空结构时滚动半天。字符串必须走JSON.stringify，直接拼原始字符串会导致内部引号和换行符把结构打乱。还有一个隐蔽问题：数字Number(value)在输入是1e100000时会输出Infinity，而 JSON 里不允许 Infinity，所以我在外层 parse 阶段就拦截了非有限数字的输入。

3.2 排序、压缩、折叠与错误定位

排序是在renderValue的 object 分支里做的，keys.sort()默认按 UTF-16 码元排序。对 JSON key 来说这个顺序基本符合预期，数字型 key 会排在前面（"1" < "10" < "2"），符合大多数人的直感。

压缩实现更简单，直接JSON.stringify(value)。这一步看起来 trivial，但要注意JSON.stringify在遇到undefined、函数、Symbol 时会静默跳过 key，好在这三种情况在标准 JSON 输入里根本不会出现，所以不会造成问题。

折叠是最占用实现量的部分。我的方案是：格式化输出的时候，同时构建一个区间映射，记录每个{或[对应的行号和它的结束行号。渲染阶段输出区不再用死板的 pre 文本，而是用一个扁平列表，每一行是一个独立的渲染单元。点击某一行行首的箭头，就把该行到结束行的区间标记为"折叠"，利用 CSS 的display: none配合虚拟滚动隐藏。这样折叠功能不依赖重新格式化，动态性能也可以接受。

错误定位的实现值得展开。JSON.parse的报错信息在 V8 里大致长这样："Unexpected token } in JSON at position 123"。我从这个字符串里用正则提取 position 数字，再拿着 position 回到源文本里逐行累加长度找到行号和列号。具体代码片段：

function parseErrorPosition(message: string): number | null { const match = /position\s+(\d+)/.exec(message); if (!match) return null; const pos = Number(match[1]); return Number.isFinite(pos) ? pos : null; }

拿到位置后，插件会在输入框里对出错 token 附近 20 个字符做一个红色波浪线标记，同时在状态栏显示"第 X 行 第 Y 列附近出现语法错误"。这个功能直接对标老牌工具的错误提示体验，而平台自带预览器至今没有这个能力，也是用户留存的隐性加分项。

3.3 性能优化与极端场景处理

JSON 格式化最大的性能敌人是"大"和"深"。大指输入体量大，深指嵌套层级深，两者要分开处理。

我用了一个 8MB 的 JSON 日志文件做压测（模拟真实生产环境），首次格式化耗时接近 1.4 秒。这个卡顿主要来自两个方面：一是JSON.parse本身要建树，二是格式化后的文本量往往是原始文本的 2~3 倍，渲染到 DOM 上直接把主线程拖住。解决方案是引入 Web Worker 做核心计算，界面线程只负责接收结果字符串：

// src/index.ts 节选 const worker = new Worker(new URL("./worker.ts", import.meta.url), { type: "module", }); worker.onmessage = (e) => { renderResult(e.data.formatted, e.data.foldRanges); };

Worker 化之后，格式化 8MB 文件耗时不变（计算时间省不掉），但主线程不再卡死，用户可以正常滚动输入框，体验上就从"白屏 4 秒"变成了"顶部出现加载中 2 秒"。这是一个用户感知极大的优化。

深的问题更危险。如果一个 JSON 嵌套超过 1 万层，递归渲染函数会直接爆栈。我的处理是在 parse 后先做一个深度检测，超过 2000 层就直接提示"嵌套过深，无法安全格式化"，并建议用户先用压缩模式降低层级。2000 层在正常开发场景里已经属于异常数据，用这个阈值做保护不会误伤合法文件。

大数精度问题也被我单独拎出来处理。标准 JSON 序列化遇到超过Number.MAX_SAFE_INTEGER的整数时会直接用科学计数法，比如明确写了一个 20 位的交易单号，格式化后会变成1.2345678901234567e+19。对于日志调试场景来说这会导致单号对不上。我在第一版里做了一个可配置项：开启"大数保护"后，字符串值如果看起来是长数字（超过 16 位纯数字），就不做类型转换而是保持原始字符串输出。这个取舍牺牲了一点理论上的 JSON 严格性，但极大增强了实际工具的可用性。

4. 发布上架与 Credits 收益策略

4.1 打包、提交与平台审核

WorkBuddy 的发布命令是wb publish，它会做三件事：把项目打包成平台要求的.wbpkg格式、生成版本签名、上传到开发者后台。上传完成后，还需在后台填写插件描述、上传截图、声明权限用途，然后提交审核。

第一版提交审核还是遇到了一些波折。第一次被驳回的理由是"插件描述与实际功能不完全匹配"。我当初写的描述里提到了"支持 JSON5"，但实际功能根本没有实现。这个暗亏提醒了我：描述宁可保守，在稳定版里千万不要提前画饼。第二次提交改成了"标准 JSON 格式化、排序、压缩和折叠"，并附上了压缩包截图，这次过了审核。整体流程从提交到通过，大概花了两天多。

审核员对工具类插件关注的点很集中：是否有恶意脚本、是否声明了不必要的权限，以及功能描述是否真实。零权限 + 纯开源的实现风格让这轮审核没有过多纠缠，这也是我一直坚持不引入网络请求的原因。

4.2 文档、截图与冷启动推广

上架不等于有人用，冷启动是一个必须主动推动的阶段。我在 README 里写了四段式结构：功能概览、使用场景、性能实测数据、常见问题。其中性能数据我用了三档真实测试结果：

截图是很关键但容易被忽视的环节。我做了两张对比图：一张是平台自带预览器输出大文件时的白屏状态，另一张是 json-formatter 输出同一个文件的有序格式化结果。有对比才有冲击力，这种截图比单纯的功能截图更容易让用户产生下载冲动。

社区运营方面，我在 WorkBuddy 的开发者论坛发了两个帖子：一个介绍插件的定位，一个专门讲大文件调试的优化经验。帖子不放插件链接，只贴测试数据，感兴趣的人自然搜索找到插件页。这个策略避开了一上来就发广告被管理的风险，最后转化率反而比想象的更好——上线第一周新增的 61 个安装里，有接近一半是从论坛帖子过来的。

4.3 数据复盘与 Credits 增长曲线

直接说结果。上线 21 天的数据是这个样子：

可以看到前三天 Credits 增长非常慢，但过了第一周之后斜率明显加大。核心原因是两个关键的动作起了作用：一是质量管理——我把用户反馈的高频崩溃问题在第二周集中修掉了一轮；二是版本更新带来的曝光——平台对及时更新的插件会给一个短暂的排序加权，加权期间的新安装量占比超过 40%。

一个值得注意的规律是：总安装量不是我追求的目标，周活跃调用才是。第 21 天安装量只有 210，但周调用到了 3800，说明每个安装用户平均每天调用 2.5 次左右，留存和质量因子都非常健康。Credits 的算法到这里就显出威力了，质量因子上来之后，同样是 100 个新安装，能拿到的 Credits 可能是低质量插件的 2~3 倍。

5. 常见问题与排查实录

5.1 我踩过的六个坑，以及是怎么填上的

开发过程远不是一条直线。下面这几个问题基本涵盖了 json-formatter 开发中最容易翻车的场景，每个都是我实际踩过并保留到最终版本的解决方案。

第一个坑：输入框卡死。现象是输入超过 2MB 的内容时，插件整个失去响应。排查后发现罪魁祸首是实时预览，每次输入都触发格式化，加上渲染 4 万行 DOM，主线程必挂。解法是改成按钮触发 + Web Worker 分离计算，这个我在 3.3 节已经详述，不再重复。

第二个坑：数字精度丢失。用户反馈"订单号从 9007199254740993 变味成了 9007199254740992"。这是我最初直接JSON.parse然后String(value)导致的。在第三个版本里我加入了大数保护配置，只对纯数字字符串做保留，不算万能但解决了绝大多数真实场景。

第三个坑：Unicode 转义显示问题。格式化后的字符串，如果用户输入是\u4e2d\u6587，默认JSON.stringify会原样保留转义序列，展示给用户的中文场景就没法读了。这个问题的解法是配置一个"是否解析 Unicode"开关，开启后用JSON.parse('"' + rawString + '"')解码代理对，但要注意不要二次转义。这个细节做得好不好，直接影响国内用户的第一印象。

第四个坑：循环引用导致无限递归。正常标准 JSON 不会有循环引用，但用户可以手写一个const a = {}; a.self = a然后再序列化出去。如果是这种特殊数据，直接递归会爆栈。我的防线是在 render 之前用 WeakSet 记录已经访问过的对象，遇到重复引用就抛错提示"数据疑似包含循环引用"。WeakSet 设计巧妙在不用手动清理，函数作用域结束自动释放。

第五个坑：BOM 头处理。用户在 Windows 下保存的 JSON 文件有时候带着 BOM 头（字节序标记），粘贴进来后JSON.parse直接报错。错误信息还是位置 0 的"Unexpected token"。解决方式是在 parse 之前做一次字符替换：input.replace(/^\uFEFF/, "")。这个 bug 不常见，但遇到一次能让用户直接放弃你的插件。

第六个坑：空对象输出多行。我第一版格式化时所有对象都强制展开大括号，结果{"a":"b","c":{}}这种结构的输出里出现大量三行一组的空对象空数组，视觉噪音极大。改成空结构紧凑输出（{}/[]）之后，整体可读性上升了一个档次。这也是我在 3.1 节代码里特别强调的原因。

5.2 常见问题速查表

5.3 平台侧的合作避坑经验

审核环节的经验前面已经说过一条，这里再补充两点。第一是版本号一致性。WorkBuddy 后台会读取 manifest 里的 version，如果和上传包里的版本不一致会直接打回。我当时因为改了代码忘了升版本号，白白浪费了一轮审核周期。现在我的习惯是：任何代码改动先动版本号，再动代码。

第二是缓存问题。本地调试的时候wb dev的热更新有极小概率出现缓存残留，遇到离谱的报错或者旧代码在跑，先试试wb clean清缓存再重启。这个玄学问题我在第三周遇到过两次，排查了大半天最终发现是缓存。

从项目上线到现在，最让我意外的是：用户对"看得见的细节"的反馈比功能本身更热情。比如错误定位的红色波浪线，比如缩进切换的实时预览，这些看似很小的细节带来的好评率远高于核心格式化功能本身。这说明在工具插件这个品类里，"不出错"只是入场券，"细节体验"才是让用户持续回来用的关键。

我现在已经在规划第二版，方向是把 JSON5 的子集支持（主要是注释和尾逗号）做进去，并加一个"路径查询"功能——用户点击结果里某个 key，输入框自动输入这个 key 的完整路径。这个需求来自用户论坛的一条高赞评论，需求真实度和优先级都很高。

最后分享一个我自己的判断：在 WorkBuddy 这种开放插件生态里，Credits 本质上是"质量因子"的积分化表达，而质量因子的核心是用户留存和活跃。与其盯着下载量和 Credits 数字，不如把精力花在用户下一次还想不想打开你的插件这件事上。一个 200 安装的插件如果人人天天用，它的长期收益一定超过一个 2000 安装但装完就吃灰的工具。少堆没用的功能，多打磨核心路径上的手感，这是我做 json-formatter 三周下来最深的一个体会。