TypeScript 插件开发指南

下面这份指南把”从 0 到能独立写 Obsidian / VS Code 插件”的 TypeScript 路线拆成 4 个阶段，每阶段给出”目标-资源-作业-坑点”四件套，按需取用即可。整个周期 3–6 周（每天 1–2 h）。

阶段 0　环境 & 心态（半天） 目标：让 .ts 文件能跑起来。
资源：

• Node.js ≥ 18 LTS
• pnpm（比 npm 快）
• VS Code 插件：TypeScript Importer、Error Lens
  作业：

1. 全局装 ts-node：pnpm add -g ts-node
2. 新建 playground/01-hello.ts：

   const msg: string = 'Hello TS'
   console.log(msg.toUpperCase())

3. 命令行跑 ts-node 01-hello.ts，看到 HELLO TS 就过关。
   坑点：

• 别急着配 Webpack／Vite，先让 ts-node 把 “写→跑” 闭环最短。
• 如果终端报 Cannot find module，90 % 是路径没写 .js（ESM 要求写全）。

阶段 1　类型系统 48 h 目标：把任何 JS 文件重写成 “零 any” 的 TS，且编译器不报错。
资源：

• 官方 Handbook：「TypeScript for JS Programmers」前半本
• 在线演练场：www.typescriptlang.org/play
  作业（按顺序，每个作业 ≤ 30 行）：
  a. 原始类型、数组、tuple
  b. interface vs type alias
  c. 联合 & 交叉 & 字面量类型
  d. 泛型函数 + 泛型约束
  e. keyof / typeof / mapped type 小抄
  f. 把 50 行祖传 JS 配置脚本重写成 TS，消灭所有隐式 any。

坑点：

• “会写 interface” ≠ “懂结构化类型”：把 {a:string} 传给 {a:string,b?:number} 能过，才是结构型子类型。
• 泛型默认推导失败时，先写 const foo = <T>(x:T):T=>x 再调用，别一上来就 <T=unknown>。

阶段 2　工程化与官方类型（1 周） 目标：能给真实项目（Obsidian/VS Code）搭出可调试、可热重载、带 lint + 测试的骨架。
资源：

• 官方 sample 插件：
  – Obsidian：github.com/obsidianmd/obsidian-sample-plugin
  – VS Code：github.com/microsoft/vscode-extension-samples
• 打包器对比文章：esbuild vs rollup（插件体量小，esbuild 秒级构建）

作业：

1. 把官方 TS 模板 git clone 下来，pnpm i → pnpm dev，能在编辑器里断点即及格。
2. 把 tsconfig.json 的 5 个最常用开关默写出来：
   target、module、moduleResolution、strict、esModuleInterop。
3. 配置 eslint + prettier，规则集用 eslint-config-standard-with-typescript，保存即自动修复。
4. 写第一个命令：
   Obsidian 版：「在当前文件末尾插入今日日期」
   VS Code 版：「在终端里执行 git rev-parse --short HEAD 并回显」
   要求：F5 调试窗口能断到源码 .ts，而不是编译后的 .js。

坑点：

• VS Code 的 launch.json 里 "outFiles" 必须指向 dist/**/*.js，否则断点映射失败。
• Obsidian 插件热重载用 pnpm dev 后，记得在 .hotreload 文件里打时间戳，否则主进程不刷新。

阶段 3　进阶类型体操 & 实战（1–2 周） 目标：能读懂并改写社区插件里常见的“复杂类型”，同时写出带单元测试的模块。
资源：

• Type Challenges（github.com/type-challenges/type-challenges）选做前 20 题（easy+medium）。
• 书籍：《TypeScript 类型编程》王红元（选读 3-6 章）。
• 测试框架：vitest（兼容 jest 语法，ESM 第一公民）。

作业：

1. 实现一个 Result<T,E> 类型，要求：
   • 编译期保证必须先判断 .ok 才能访问 .value
   • 运行时提供 map/flatMap
     写完补 100 % 分支覆盖的测试。
2. 把 Obsidian 的 Plugin 类声明文件 obsidian.d.ts 里你最常用的 3 个 API 抄一遍，并加上中文注释，发 Gist。
3. 给 VS Code 写一个 TreeView 示例：左侧树节点点击后，在编辑器插入对应 snippet。要求节点图标用 Codicon，且支持多级嵌套。

坑点：

• 类型体操别沉迷：项目代码里出现 T extends keyof any ? ... : ... 嵌套三层以上，就要考虑抽象成工具类型文件，别让业务代码可读性爆炸。
• TreeView 的 getChildren 返回的是 Thenable<YourItem[]>，忘记 Promise.resolve 会整棵树都出不来。

阶段 4　持续精进（长期）

1. 每周读一次 TS 4.x/5.x 发布笔记，把新语法（如 satisfies、const type parameters）立刻用到自己插件里。
2. 跟踪社区模板：
   • github.com/liamcain/obsidian-calendar-plugin（学习大型插件的架构）
   • github.com/microsoft/vscode-python（看微软怎么写百万行级 TS）
3. 自己发插件 → 收集 issue → 回炉重构，循环 3 轮，基本就“出师”了。

速查小抄（打印贴墙）

一句话总结
“先把类型当测试，再把工程当产品，最后用插件刷经验值。”
按上面 4 个阶段一路打怪升级，你就能用 TypeScript 写出让别人愿意装、愿意 star 的 Obsidian / VS Code 插件。祝编码愉快！