Node.js 模块系统深度：CommonJS、ESM 与工程化实践

CommonJS 哲学：运行时决定，加载即执行（同步）
  require('a')          → 立即解析、立即执行、缓存
  module.exports = x    → 导出值（拷贝语义，缓存引用）

ESM 哲学：编译期决定，加载可异步（静态）
  import a from 'a'     → 静态依赖图，可 tree-shaking
  export const x        → 导出绑定（实时绑定，可读写）

1. 内置模块（node:fs、node:path 等）
2. 相对路径：./x 或 ../x（补扩展名：.js → .json → .node）
3. node_modules 逐级向上查找（当前目录 → 上级 → ... → 根）
4. 找不到 → MODULE_NOT_FOUND

// 模块加载器伪代码（理解缓存机制）
const Module = require('module');
Module._cache = {}; // 全局模块缓存

function loadModule(id) {
  if (Module._cache[id]) return Module._cache[id].exports; // 命中缓存
  const m = new Module(id);
  Module._cache[id] = m;          // 先入缓存，防循环依赖死循环
  m.load();                        // 同步加载并执行
  return m.exports;
}

// db.js —— 单例连接（缓存生效）
const conn = new Connection();
module.exports = conn;

// factory.js —— 每次 require 都新建（但必须手动调用）
module.exports = function createConn() { return new Connection(); };

// utils.js —— 导出 20 个函数
export function used() { ... }
export function unused() { ... }

// app.js —— 只 import 了一个
import { used } from './utils.js';
// 打包后 unused 从产物中被移除

// counter.js
export let count = 0;
export function inc() { count++; }

// app.js
import { count, inc } from './counter.js';
console.log(count); // 0
inc();
console.log(count); // 1  —— ESM 下是 1；CJS 下通常还是 0

// config.js —— 顶层 await 初始化
export const config = await loadRemoteConfig();

// package.json
{
  "type": "module",   // "module"=当前包文件按 ESM 解析；"commonjs"（缺省）按 CJS
  "exports": {
    ".": {
      "import": "./dist/index.mjs",  // ESM 环境拿到的入口
      "require": "./dist/index.cjs"  // CJS 环境拿到的入口
    },
    "./sub": "./dist/sub.mjs"
  }
}

// 双格式写法：把纯逻辑写一份，分别编译出 .mjs 与 .cjs
// 或在 package.json 里同时保留 type 字段 + exports 双入口

// 用户错误 import 包内部文件，exports 直接报错
import x from 'pkg/dist/internal.js'; // ✗ 未在 exports 白名单 → ERR_PACKAGE_PATH_NOT_EXPORTED

// a.js
const b = require('./b.js');
exports.name = 'A';
exports.tell = () => `A 说 ${b.name}`; // b 在 a 加载完前只暴露了部分

// b.js
const a = require('./a.js');
exports.name = 'B';
exports.tell = () => `B 说 ${a.name}`; // a 此刻 exports.name 可能还是 undefined

// 延迟取值示例：函数体内再 require，避免顶层拿到半成品
exports.tell = () => {
  const b = require('./b.js'); // 此时 b 已完整加载
  return `A 说 ${b.name}`;
};

# pnpm 基本操作
pnpm add express          # 安装并写入 dependencies
pnpm add -D typescript    # devDependencies
pnpm dlx prettier --check # 临时执行，不污染依赖
pnpm -r test              # 递归执行所有 workspace 包的 test

monorepo/
  packages/
    core/        # 公共核心逻辑
    api/         # 业务 API
    cli/         # 命令行工具
  pnpm-workspace.yaml

# pnpm-workspace.yaml
packages:
  - "packages/*"

// packages/api/package.json
{
  "name": "@org/api",
  "exports": {
    ".": "./dist/index.js"
  },
  "dependencies": {
    "@org/core": "workspace:*"   // 本地链接，发布时改写
  }
}