分析总结node中不同文件名后缀如何导入node内置模块

解决 Node.js 项目中 `node:process` 模块导入问题

遇到的问题

最近在 Node.js 项目中遇到了一个奇怪的模块导入问题。在 .mts 文件（TypeScript 的 ESM 模块文件）中，当我尝试导入 node:process 模块时：

typescript 复制代码

import process from "node:process";

遇到了以下错误：

arduino 复制代码

找不到模块"node:process"或其相应的类型声明

但令人困惑的是，在同一个项目的 .cjs 文件（CommonJS 模块文件）中，使用相同的导入语句却能正常工作：

javascript 复制代码

const process = require("node:process");

分析原因

1. Node.js 的模块系统差异

首先需要理解 Node.js 中不同模块系统的行为差异：

CommonJS (CJS) : Node.js 传统的模块系统，使用 require() 语法
ES Modules (ESM) : JavaScript 的标准模块系统，使用 import 语法

node: 前缀是 Node.js 14.18.0 或更高版本引入的特性，用于明确指示导入的是 Node.js 内置模块。

2. TypeScript 的模块解析

TypeScript 在处理 .mts 文件（ESM 模块）和 .cts 文件（CJS 模块）时有不同的行为：

对于 ESM 模块，TypeScript 会进行更严格的模块解析
默认情况下，TypeScript 的类型定义可能不包含 node: 前缀的模块声明

3. 解决方案探究

经过研究和实验，发现有以下几种解决方案：

方案一：使用传统导入方式（推荐）

typescript 复制代码

import process from "process";

这种方式兼容性最好，在所有 Node.js 版本和模块系统中都能工作。

方案二：更新 TypeScript 和 Node.js 类型定义

确保你使用的是最新版本的 TypeScript 和 @types/node：

bash 复制代码

npm install --save-dev typescript @types/node@latest

方案三：在 tsconfig.json 中添加类型声明

json 复制代码

{
  "compilerOptions": {
    "types": ["node"]
  }
}

方案四：使用条件导出

对于需要同时支持 ESM 和 CJS 的库，可以在 package.json 中配置：

json 复制代码

{
  "exports": {
    "import": "./index.mjs",
    "require": "./index.cjs"
  }
}

4. 根本原因

问题的根本原因在于：

TypeScript 对 node: 前缀的支持需要较新版本
ESM 和 CJS 的模块解析机制不同
类型定义文件可能需要显式配置才能识别 node: 前缀

总结

在 Node.js 项目中使用 node: 前缀导入内置模块时，需要注意以下几点：

版本兼容性：确保 Node.js 版本 ≥14.18.0，TypeScript 版本 ≥4.7
模块系统差异 ：ESM 和 CJS 对 node: 前缀的处理可能不同
类型声明 ：更新 @types/node 并在 tsconfig.json 中正确配置
推荐做法 ：对于大多数场景，直接使用 import process from "process" 是更安全的选择

如果你正在开发需要同时支持 ESM 和 CJS 的库，建议：

使用现代构建工具（如 tsup、vite 等）
明确声明 package.json 中的 type 和 exports 字段
编写兼容性测试用例

通过理解 Node.js 模块系统的工作原理和 TypeScript 的模块解析机制，可以避免这类导入问题，提高开发效率。