够用的 Node.js 与工具链

一、三个角色：JavaScript、Node、浏览器The Cast

JavaScript（JS）是语言本身，像一份菜谱；照着做菜的程序叫运行时（runtime）。浏览器是最常见的一种；2009 年 JS 引擎被搬出浏览器做成独立程序，就是 Node.js。

二、包与包管理器：npm 与 pnpmPackages

包（package）是发布出来复用的代码，相当于手机 App；全发布在 npm registry（应用商店）。包管理器负责下载安装：老牌叫 npm，本项目用升级版 pnpm（更快、更省磁盘）。

任何包（含仓库本身和每个子包）根目录都有 package.json：

{
  "name": "@deepseek-ai/dsh-tools",   // @组织/包名 叫"scope"（命名空间）
  "version": "0.1.0",                // 语义化版本
  "type": "module",                 // ESM 模块标准（下一节讲）
  "dependencies": {                  // 运行时依赖：装我必须先装它们
    "@deepseek-ai/cordis": "workspace:*"
  }
}

本仓库一个真实包的 package.json（节选）

pnpm install 把所有依赖递归下载到 node_modules/，相当于食材一次买齐。

三、Monorepo：一个仓库，几十个包Monorepo

monorepo：许多包放同一仓库统一管理，像写字楼租户——共用电梯物业，各自独立经营。

• 根目录 pnpm-workspace.yaml 声明哪些目录的包算租户（主要是 packages/*）；
• 每个包在 packages/<组>/<包名>/ 下，可独立发布；
• 互相引用写 "workspace:*"（用楼里的版本）。

四、ESM 模块：import 与 exportESM

模块就是一个 JS/TS 文件，官方标准 ESM 用两个关键字连接：

// math.ts —— 导出
export function add(a: number, b: number) { return a + b }
export const PI = 3.14

// main.ts —— 导入
import { add, PI } from './math.ts'
console.log(add(1, 2))  // 3

像快递柜：export 放东西进柜子，import 凭取件码去拿。老标准 CommonJS（require）本仓库不用，看到 require 要警惕。

五、TypeScript：带类型的 JavaScriptTypeScript

TypeScript（TS）= JS + 类型标注，后缀 .ts，先编译成 .js 才能跑。相当于合同：类型写死，违反了开工前报错，不是跑到一半崩。

function greet(name: string): string {
  return 'Hello, ' + name
}
greet('Ada')   // ✔ 合同允许
greet(42)      // ✘ 编译期就报错

本项目中反复见到的类型写法（速查）

六、终端与 pnpm runScripts

package.json 的 scripts 给常用命令起短名字：

"scripts": {
  "build": "pnpm run -r build",   // 递归让每个子包各自 build
  "test": "vitest run"            // 用 vitest 跑测试
}

pnpm run build = 执行引号里的原始命令，相当于通讯录昵称。完整清单见 命令速查表。