进阶 oclif.io 2026-10-18 02:37:03 · 33 阅读

第22章 @oclif/core 3.0.0 支持 ESM 插件开发与互操作性

@oclif/core 3.0.0 版本正式支持 ESM 插件开发及 CJS/ESM 互操作性。这意味着,你可以使用 CJS 编写根插件,同时使用 ESM 编写子插件,反之亦然。 互操作性概述 以下是 ESM/CJS 互操作性的高层概览: ESM 根插件 - ✅ 安装 CJS 插件 - ✅ 安装 ESM 插件 - ✅ 链接 CJS 插件 - ⚠️ 链接 ESM 插件 对于将 ts-node 作为开发依赖项的已链接 ESM 插件,自动编译功能将无法使用。相反,oclif 将使用插件的已编译源码。这表示你在执行任何命令之前,必须先自行编译该插件。一旦 Node 生态系统提供更全面的原生 ESM 支持,我们计划重新支持此功能。 不过,如果你希望已链接的 ESM 插件具备运行时自动编译能力,可以将开发依赖项中的 ts-node 替换为 tsx。 CJS 根插件 - ✅ 安装 CJS 插件 - ✅ 安装 ESM 插件 - ✅ 链接 CJS 插件 - ⚠️ 链接 ESM 插件 对于将 ts-node 作为开发依赖项的已链接 ESM 插件,自动编译功能将无法使用。相反,oclif 将使用插件的已编译源码。这表示你在执行任何命令之前,必须先自行编译该插件。一旦 Node 生态系统提供更全面的原生 ESM 支持,我们计划重新支持此功能。 不过,如果你希望已链接的 ESM 插件具备运行时自动编译能力,可以将开发依赖项中的 ts-node 替换为 tsx。 创建 ESM 插件 要生成新的 ESM 插件,请运行 `oclif generate` 命令,并在提示选择模块类型时选择 ESM: $ npx oclif generate my-esm-plugin
? Select a module type
CommonJS
❯ ESM
将 CJS 插件迁移到 ESM 更新 bin 脚本 首先需要更新 `bin` 目录下的 bin 脚本。 bin/dev → bin/dev.js 将 `bin/dev` 重命名为 `bin/dev.js`,并用以下代码替换原有代码: #!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning

import {execute} from '@oclif/core'

await execute({development: true, dir: import.meta.url})
这利用了 oclif 的 `execute` 函数,它会为你处理所有开发环境的设置工作。你不再需要设置 `NODE_ENV` 环境变量或向 ts-node 注册项目。你仍然可以在执行 CLI 之前调整 oclif 配置。例如: #!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning

import {execute, settings} from '@oclif/core'

settings.performanceEnabled = true

await execute({development: true, dir: import.meta.url})
bin/run → bin/run.js​ 将 bin/run 重命名为 bin/run.js,并把原有代码替换为以下内容: #!/usr/bin/env node

import {execute} from '@oclif/core'

await execute({dir: import.meta.url})
更新 tsconfig.json​ 更新完 bin 脚本后,接下来需要修改 tsconfig.json,加入以下配置项: {
"compilerOptions": {
"module": "ES2020",
"moduleResolution": "node16",
},
"ts-node": {
"esm": true
}
}
在 package.json 中设置 "module" 类型​ 在 package.json 中添加 "type": "module",这样你的文件就会以 ESM 模块的方式加载。 更新 bin 脚本的引用​ 你需要把所有指向 bin 脚本的引用改为带 .js 扩展名的版本。比如 package.json 中的 bin 字段要从: "bin": {
"my-cli": "./bin/run"
},
改为: "bin": {
"my-cli": "./bin/run.js"
},
如果 .vscode/launch.json 或 package.json 的 scripts 里也引用了 bin 脚本,同样需要一并更新。 更新 mocharc 配置​ 要让 mocha 测试正常运行,还需要做以下几处修改: 在 .mocharc.json 中添加: {
"node-option": [
"loader=ts-node/esm"
]
}
更新 test/helpers/init.js 如果你的插件是通过 oclif generate 生成的,通常会有一个 test/helpers/init.js 文件需要更新。你可以把扩展名改为 .cjs,也可以把文件顶部的 require 改成 import: import path from 'node:path'
另外,这个文件已经没有存在的必要,直接删掉也没问题。

评论 (0)