1. 从"plugins"这个标题说起：插件系统到底在解决什么问题
"plugins"这个词单独拎出来，信息量其实非常少。但结合热搜词里反复出现的cursor、plugin.json、TypeScript SDK、CLI、harness failed to load plugins这些关键词，基本可以判断出讨论的场景：一个基于 TypeScript 的插件宿主系统，通过plugin.json做声明式配置，通过 CLI 做加载与调试，SDK 提供插件开发接口。这类架构在编辑器、构建工具、AI 编程助手、自动化平台里非常常见。
我最早接触插件系统是在做内部工具链的时候。当时的需求很朴素：主程序功能固定，但不同团队想要不同的能力扩展，比如自定义代码检查规则、自定义数据导出格式、自定义快捷键行为。如果每来一个需求就改主程序，代码会迅速腐化。插件系统的本质就是把"变化的部分"从"稳定的部分"里剥离出去，让主程序只负责调度和生命周期管理，具体能力由插件提供。
但插件系统真正难的地方从来不是"怎么加载一个 JS 文件"，而是：插件怎么声明自己需要什么、宿主怎么知道插件是否可用、加载失败时怎么定位、多个插件之间怎么隔离、版本不兼容怎么办。热搜里harness failed to load plugins web boot: 2 entries did not activate这种报错，就是典型的"加载链路某一环断了"的表现。这篇文章我会围绕一个 TypeScript 插件系统的完整实现路径，把plugin.json的设计、SDK 的接口边界、CLI 的调试能力、以及加载失败的排查方法讲透。
适合读这篇的人：正在设计插件架构的工程师、需要给现有工具加扩展能力的开发者、以及被failed to load plugins类报错卡住、想搞清楚背后机制的人。不需要你是插件系统专家，但最好对 TypeScript 和 Node 生态有基本了解。
2. plugin.json 的字段设计：声明式配置的取舍
2.1 为什么用 JSON 而不是直接读 package.json
很多人第一反应是：插件本身就是一个 npm 包，直接读package.json不就行了？我一开始也这么想，后来发现不行。package.json的语义是"包管理元数据"，它关心的是依赖、脚本、发布信息；而插件系统关心的是"这个插件向宿主暴露什么能力"。两者混在一起会导致字段污染，而且package.json的字段名是 npm 生态的公共约定，你往里塞自定义字段容易和未来的标准冲突。
所以独立一个plugin.json是更干净的做法。它的职责非常单一：告诉宿主这个插件是谁、能做什么、需要什么、怎么被激活。下面是我在实际项目里用过的一套字段设计，经过几轮迭代后比较稳定：
{ "id": "com.example.linter", "name": "Example Linter", "version": "1.2.0", "main": "./dist/index.js", "activationEvents": ["onCommand:example.lint", "onLanguage:typescript"], "contributes": { "commands": [ { "command": "example.lint", "title": "Run Lint" } ], "configuration": { "rules": { "type": "array", "default": [] } } }, "engines": { "host": "^2.0.0" }, "dependencies": { "sdk": "^1.0.0" } }这里每个字段都有明确意图。id用反向域名风格，避免不同来源的插件撞名；activationEvents是懒加载的关键，宿主不需要在启动时把所有插件都实例化，而是等某个事件触发时再加载对应插件，这对启动性能影响巨大；contributes是声明式的能力注册，宿主可以只读这个字段就构建出命令面板、配置界面，不需要执行插件代码；engines做版本约束，防止插件调用宿主不存在的 API。
2.2 activationEvents 的设计陷阱
activationEvents看起来简单，实际是最容易踩坑的地方。我见过最常见的错误是：插件作者把所有事件都写进去，比如["*"]，想着"反正都能激活"。结果宿主启动时被迫加载所有插件，冷启动时间从 200ms 涨到 3 秒。另一个极端是事件写得太窄，用户执行某个命令时插件没被激活，报"command not found"，但其实是激活条件没匹配上。
我的经验是：activationEvents 应该精确对应 contributes 里声明的东西。你声明了一个命令example.lint，就应该有onCommand:example.lint；你声明了对 TypeScript 的支持，就应该有onLanguage:typescript。这两者要能对得上，否则就是配置错误。可以在 CLI 里加一个校验命令，加载时自动比对contributes和activationEvents，不匹配就警告。
提示：
activationEvents里的事件名建议用命名空间前缀，比如onCommand:、onLanguage:、onFileSystem:，避免和宿主内置事件冲突。事件名一旦发布就不要改，因为插件作者会依赖它。
2.3 版本约束字段怎么写才不坑人
engines.host这个字段我踩过坑。早期我用的是精确版本"2.0.0"，结果宿主升级到2.0.1后所有插件都报不兼容。后来改成 semver range"^2.0.0"，表示"2.x 系列都兼容"。这里的关键是：宿主 API 的破坏性变更必须升主版本号，只要遵守这个约定，^就是安全的。
但还有一个更隐蔽的问题：插件依赖的 SDK 版本和宿主内置的 SDK 版本可能不一致。如果 SDK 是独立发布的 npm 包，插件npm install时会装自己那份，运行时可能出现两份 SDK 实例，导致instanceof判断失败、单例状态不共享。解决办法是宿主把 SDK 作为 peer dependency 暴露，插件在plugin.json里声明dependencies.sdk，运行时由宿主注入，而不是插件自己打包。
3. TypeScript SDK 的接口边界：哪些该暴露，哪些必须藏
3.1 宿主 API 的最小暴露原则
设计 SDK 时最大的诱惑是"多暴露一点，插件作者方便"。我强烈建议反着来：能不给的就不给，必须给的给最小面。原因很简单，SDK 一旦发布就是契约，你暴露的每个方法都要长期维护，改签名就是破坏性变更。而且暴露越多，插件能做的事越多，宿主的安全边界就越模糊。
一个典型的 SDK 接口大概长这样：
export interface PluginContext { readonly pluginId: string; readonly storage: KeyValueStorage; readonly logger: Logger; readonly commands: CommandRegistry; readonly workspace: WorkspaceApi; readonly config: ConfigApi; } export interface CommandRegistry { register(id: string, handler: (...args: unknown[]) => Promise<void>): Disposable; execute(id: string, ...args: unknown[]): Promise<unknown>; } export interface Disposable { dispose(): void; }注意几个设计点。PluginContext是只读的，插件不能替换宿主注入的对象；register返回Disposable，插件卸载时调用dispose()清理注册，这是防止内存泄漏的关键；storage是 key-value 抽象，插件不能直接碰文件系统，宿主可以控制存储位置和配额。
3.2 生命周期钩子怎么设计
插件从加载到卸载有一系列状态：discovered（发现）→activated（激活）→deactivated（停用）→disposed（销毁）。SDK 里对应的钩子通常是：
export interface Plugin { activate(context: PluginContext): Promise<void> | void; deactivate?(): Promise<void> | void; }activate是必须的，宿主调用它时插件完成命令注册、事件监听等初始化。deactivate是可选的，用于释放资源。这里有个容易忽略的点：activate里如果抛异常，宿主必须能捕获并标记插件为失败状态，而不是让整个宿主崩溃。我见过太多插件系统因为一个插件 activate 失败导致主程序起不来，这是设计缺陷。
实测下来，activate里做异步操作要特别小心。如果插件在 activate 里await一个网络请求，宿主启动就会被阻塞。我的做法是：activate 里只做同步的注册操作，耗时的初始化放到第一次实际使用时再做，或者用setTimeout延后。宿主侧也要加超时保护，比如 activate 超过 5 秒就强制标记失败。
3.3 类型定义怎么共享给插件作者
TypeScript 插件系统的一大优势是类型安全，但前提是插件作者能拿到宿主的类型定义。常见做法是发布一个@host/sdk的 npm 包，里面只有.d.ts和少量运行时辅助函数。插件项目npm install @host/sdk后就能获得完整的类型提示。
这里有个细节：SDK 包的版本要和宿主 API 版本对齐。我建议 SDK 包的主版本号直接跟宿主 API 主版本号走，@host/sdk@2.x对应宿主 API 2.x。插件在plugin.json里声明dependencies.sdk: "^2.0.0"，宿主加载时校验，不匹配就拒绝加载并给出明确提示，而不是等到运行时才报莫名其妙的错。
4. CLI 在插件开发调试中的真实作用
4.1 为什么插件系统离不开 CLI
插件开发有个天然的痛点：插件代码运行在宿主环境里，但开发者想独立调试。如果没有 CLI，开发者只能把插件装进宿主，重启宿主，看日志，改代码，再重启，循环非常慢。CLI 的价值就是把这个循环缩短，提供独立的加载、校验、调试能力。
一个实用的插件 CLI 通常包含这些命令：
| 命令 | 作用 | 使用场景 |
|---|---|---|
plugin validate | 校验 plugin.json 格式和字段 | 提交前自检 |
plugin list | 列出已发现的插件及状态 | 排查加载问题 |
plugin activate <id> | 手动激活指定插件 | 调试激活逻辑 |
plugin deactivate <id> | 停用插件 | 测试清理逻辑 |
plugin logs <id> | 查看插件日志 | 定位运行时错误 |
plugin validate是我用得最多的。它会在不启动宿主的情况下，读取plugin.json，检查必填字段、semver 格式、activationEvents 和 contributes 的一致性。很多failed to load plugins的报错，其实在 validate 阶段就能发现。
4.2 加载失败的排查链路怎么走
热搜里harness failed to load plugins web boot: 2 entries did not activate这种报错，信息量其实很大。"2 entries did not activate" 说明宿主发现了 2 个插件条目，但激活阶段失败了。排查应该按这个顺序走：
- 确认插件是否被发现。
plugin list看这两个插件在不在列表里。如果不在，说明发现阶段就失败了，检查插件目录、plugin.json是否存在、id是否重复。 - 确认 plugin.json 是否合法。
plugin validate跑一遍，看有没有字段错误、版本不匹配。 - 确认激活条件是否满足。如果插件声明了
onCommand:xxx，但没有任何地方触发这个命令，插件就不会激活，这是正常的懒加载行为，不是 bug。 - 看激活时的异常。
plugin logs或宿主日志里应该有 activate 抛出的堆栈。常见原因是依赖缺失、SDK 版本不匹配、activate 里访问了未初始化的资源。 - 确认依赖是否装齐。插件目录下
node_modules是否完整，main指向的文件是否存在。
我踩过最坑的一次是：插件main字段写的是./dist/index.js，但构建产物实际在./out/index.js，宿主加载时找不到文件，报的却是"插件激活失败"，误导了很久。所以plugin validate里一定要检查main指向的文件是否存在。
4.3 CLI 的退出码和输出格式
CLI 要能被 CI 集成，退出码必须规范：成功返回 0，校验失败返回非 0。输出格式建议支持--json，方便脚本解析。比如plugin list --json输出：
{ "plugins": [ { "id": "com.example.linter", "status": "activated", "version": "1.2.0" }, { "id": "com.example.formatter", "status": "failed", "error": "SDK version mismatch" } ] }这样在 CI 里可以写plugin validate --json | jq '.errors | length'来判断是否有错误。别小看这个，插件生态大了以后，自动化校验能省掉大量人工排查。
5. 插件隔离与安全：别让一个插件拖垮整个宿主
5.1 进程内隔离的局限
大多数 TypeScript 插件系统跑在同一个 Node 进程里，插件和宿主共享内存空间。这意味着插件可以访问全局对象、修改原型链、甚至影响宿主行为。进程内隔离只能做到"逻辑隔离"，做不到"安全隔离"。
我的做法是：用 Proxy 包装注入给插件的 context，拦截对未暴露属性的访问。比如插件想访问context.process，Proxy 直接抛错。这不能防住所有情况（插件还是能通过globalThis拿到全局对象），但能防住大部分误用。真正的安全隔离需要 worker 线程或子进程，但那样插件和宿主通信要走序列化，性能和开发体验都会下降，大多数场景不值得。
5.2 资源配额与超时保护
插件可能写出死循环、内存泄漏、无限递归。宿主必须有能力兜底。我一般会加这几层保护：
- 激活超时：activate 超过 N 秒未返回，标记失败。
- 命令执行超时：插件注册的命令执行超过 N 秒，中断并报错。
- 内存监控：定期采样插件相关内存，超过阈值告警。
- 异常隔离：插件抛出的异常在宿主边界被捕获，记录日志，不影响其他插件。
这些保护不是万能的，但能让"一个插件出问题导致整个宿主不可用"的概率大幅降低。实测下来，激活超时和命令超时是最有效的两道防线。
5.3 插件权限声明
如果插件系统面向第三方开放，权限声明就很重要。可以在plugin.json里加permissions字段：
{ "permissions": ["storage", "commands", "workspace:read"] }宿主加载时检查插件声明的权限，运行时对未授权的能力调用直接拒绝。这样用户在安装插件时能看到它需要什么权限，做出知情选择。权限模型不用一开始就做得很细，但要有，否则后期想加会面临兼容性问题。
6. 从零搭一个最小可用的插件系统：关键代码路径
6.1 插件发现与注册表
宿主启动时第一步是发现插件。通常是扫描指定目录下的子目录，每个子目录里找plugin.json：
import { readdir, readFile } from 'fs/promises'; import { join } from 'path'; interface PluginManifest { id: string; name: string; version: string; main: string; activationEvents: string[]; engines: { host: string }; } async function discoverPlugins(rootDir: string): Promise<PluginManifest[]> { const entries = await readdir(rootDir, { withFileTypes: true }); const manifests: PluginManifest[] = []; for (const entry of entries) { if (!entry.isDirectory()) continue; const manifestPath = join(rootDir, entry.name, 'plugin.json'); try { const raw = await readFile(manifestPath, 'utf-8'); const manifest = JSON.parse(raw) as PluginManifest; manifests.push(manifest); } catch (err) { console.warn(`Skip ${entry.name}: ${(err as Error).message}`); } } return manifests; }注意这里对单个插件解析失败做了容错，跳过而不是整体失败。这是插件系统的基本素养：一个坏插件不应该阻止其他插件加载。
6.2 激活调度器
发现之后是激活。调度器维护一个事件到插件的映射，事件触发时激活对应插件：
class ActivationScheduler { private eventMap = new Map<string, Set<string>>(); private activated = new Set<string>(); register(manifest: PluginManifest) { for (const event of manifest.activationEvents) { if (!this.eventMap.has(event)) this.eventMap.set(event, new Set()); this.eventMap.get(event)!.add(manifest.id); } } async fire(event: string, loader: (id: string) => Promise<void>) { const ids = this.eventMap.get(event); if (!ids) return; for (const id of ids) { if (this.activated.has(id)) continue; try { await loader(id); this.activated.add(id); } catch (err) { console.error(`Activate ${id} failed:`, err); } } } }这个调度器保证了插件只激活一次，且激活失败不影响其他插件。loader由宿主提供，负责实际加载模块并调用activate。
6.3 模块加载与上下文注入
加载插件模块时，宿主需要注入PluginContext：
async function loadPlugin(manifest: PluginManifest, host: HostServices): Promise<void> { const modulePath = join(pluginRoot, manifest.id, manifest.main); const mod = await import(modulePath); const plugin = mod.default ?? mod; const context = createContext(manifest.id, host); await plugin.activate(context); }这里用动态import()而不是require，因为 ESM 是趋势，而且动态 import 支持异步加载。createContext负责构造注入对象，把宿主能力包装后传给插件。
7. 那些文档不会写的实操心得
7.1 插件热重载的实现代价
开发时最想要的是热重载：改插件代码，不重启宿主就生效。实现思路是监听文件变化，卸载旧插件（调用 deactivate、清理注册），重新加载。但这里有个大坑：Node 的模块缓存。import()同一个路径第二次会返回缓存，不会重新执行。解决办法是在路径上加查询参数?t=${Date.now()}强制刷新，但这会导致内存里堆积旧模块，长期运行会泄漏。
我的建议是：热重载只在开发模式开启，生产环境关闭。开发时接受一定的内存增长，重启宿主定期清理。别为了热重载把架构搞复杂，得不偿失。
7.2 插件日志的归属问题
插件日志如果不加区分，和宿主日志混在一起，排查时非常痛苦。我的做法是给每个插件一个带pluginId前缀的 logger，输出格式统一为[plugin:com.example.linter] message。这样 grep 一下就能过滤出某个插件的所有日志。CLI 的plugin logs <id>就是基于这个前缀做的过滤。
7.3 版本升级时的兼容策略
宿主 API 升级时，老插件可能不兼容。我的策略是：主版本升级时，宿主同时支持新旧两套 API 一段时间，通过engines.host判断插件用哪套。比如宿主 2.0 同时支持^1.0.0和^2.0.0的插件，内部做适配层。等大部分插件升级后再移除旧 API。这样给插件作者留出迁移时间，避免升级即全挂。
7.4 别忽略插件的卸载清理
很多插件系统只关心加载，不关心卸载。结果插件停用后，它注册的命令还在、监听的事件还在、占用的资源没释放。Disposable模式就是解决这个的：插件注册任何东西都返回一个dispose函数，宿主在停用时统一调用。我建议在 SDK 里强制这个模式，register类方法必须返回Disposable，不返回就类型报错。
8. 插件生态长期维护的几个判断
做插件系统，技术实现只是第一步，长期维护才是真正的挑战。我观察下来，能活下来的插件生态都有几个共同点。
第一，SDK 稳定优先于功能丰富。插件作者最怕的是今天写的代码明天就不能用了。宁可 SDK 功能少一点，也要保证已发布 API 的稳定性。破坏性变更必须走主版本号，且提前公告。
第二，文档和示例比 API 本身更重要。插件作者上手成本高，生态就起不来。一个能跑通的最小示例、一份字段说明、一个 CLI 校验工具，这三样东西的价值超过多暴露十个 API。
第三，加载失败要有可读的错误信息。failed to load plugins这种笼统报错是生态杀手。每个失败点都要给出具体原因：是文件不存在、版本不匹配、还是 activate 抛异常。错误信息里带上插件 id 和具体字段，能省掉大量社区提问。
第四，给插件作者提供本地调试能力。CLI 的 validate、list、logs 这些命令，看起来不起眼，但直接决定了插件作者的开发体验。开发体验好，愿意写插件的人就多。
我在实际项目里最大的体会是：插件系统的复杂度不在加载器本身，而在边界处理。加载成功是常态，加载失败才是需要花 80% 精力设计的地方。把失败路径想清楚，把错误信息做扎实，把清理逻辑写完整，这个插件系统才算真正可用。至于功能多不多，反而是后面慢慢加的事。
