把项目从 CommonJS 迁移到 ES 模块时，`__dirname` 和 `__filename` 突然不可用是很多人遇到的第一个硬钉子。在 CommonJS 里这两个变量由模块包装函数直接注入，随手拼个相对路径读配置文件、定位静态资源目录都很方便；切换到 `type: "module"` 或 `.mjs` 之后，同样的代码直接抛 `ReferenceError: __dirname is not defined`。这个问题的根源在于 ESM 的模块解析上下文不再提供这两个全局变量，而 `import.meta.url` 成了新的入口。实际开发中，读取模板、定位证书、计算日志目录、在 CLI 工具里找 package.json 都会踩到它。下面从报错现场出发，把几种可靠的替代写法、跨平台差异和工程里的落地方式讲清楚。

先看一个最典型的报错场景。假设有一个 ESM 模块要读取同目录下的 `config.json`：

```js
// config-loader.mjs
import { readFileSync } from 'node:fs';
import { join } from 'node:path';

const raw = readFileSync(join(__dirname, 'config.json'), 'utf8');
export const config = JSON.parse(raw);
```

运行后直接报错：

```
ReferenceError: __dirname is not defined in ES module scope
This file is being treated as an ES module because it has a '.mjs' file extension
```

Node 的提示已经给出了方向：ESM 里没有注入 `__dirname`。最直接的修法是利用 `import.meta.url` 拿到当前模块的 `file://` URL，再转成文件系统路径。

```js
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const raw = readFileSync(join(__dirname, 'config.json'), 'utf8');
```

`fileURLToPath` 处理了 URL 编码问题，比如路径里带空格或中文时，直接对 `import.meta.url` 做字符串截取会得到 `%20` 之类的转义片段，读文件就会失败。这也是为什么不要图省事写 `import.meta.url.replace('file://', '')`，在 Windows 上还会遇到盘符前多一个斜杠的问题。

如果只是要定位当前目录，Node 20.11 之后提供了 `import.meta.dirname` 和 `import.meta.filename`，可以直接用：

```js
import { join } from 'node:path';

const raw = readFileSync(join(import.meta.dirname, 'config.json'), 'utf8');
```

这个写法干净，但老版本 Node 不认，如果项目还要兼容 18.x，就需要保留 `fileURLToPath` 的写法，或者在构建阶段做条件处理。

另一个常见误区是把 `process.cwd()` 当成 `__dirname` 的替代。两者语义完全不同：`cwd` 是进程启动时的工作目录，取决于用户在哪个目录执行 `node` 命令；`__dirname` 是当前模块文件所在目录。写 CLI 工具时如果用它去读包内的模板文件，用户换个目录运行就找不到文件了。只有明确需要“相对于用户当前工作目录”的场景，比如读取用户传入的相对路径参数，才该用 `cwd`。

```js
// 错误：把包内资源和用户工作目录混在一起
const template = readFileSync(join(process.cwd(), 'templates', 'mail.html'));

// 正确：包内资源相对于模块自身定位
const template = readFileSync(join(import.meta.dirname, 'templates', 'mail.html'));
```

在真实项目里，这类路径代码往往散落在多个模块，每处都写一遍 `fileURLToPath` 很啰嗦。可以在一个小的工具模块里统一导出：

```js
// paths.mjs
import { fileURLToPath } from 'node:url';
import { dirname } from 'node:path';

export function getDirname(metaUrl) {
 return dirname(fileURLToPath(metaUrl));
}

export const rootDir = getDirname(import.meta.url);
```

但要注意，工具函数必须接收调用方的 `import.meta.url`，如果在工具模块内部直接写 `import.meta.url`，拿到的永远是工具模块自己的路径，而不是调用方的。这是个很容易写错的地方：

```js
// 错误：无论谁调用，返回的都是 paths.mjs 所在目录
export function getCallerDir() {
 return dirname(fileURLToPath(import.meta.url));
}

// 正确：由调用方传入自己的 import.meta.url
export function dirOf(metaUrl) {
 return dirname(fileURLToPath(metaUrl));
}
```

TypeScript 项目里还会碰到类型报错。`tsconfig.json` 的 `module` 设为 `NodeNext` 时，`import.meta.dirname` 在旧版 `@types/node` 里没有声明，需要升级类型包；如果暂时不能升级，可以自己补一个声明：

```ts
declare global {
 interface ImportMeta {
 dirname: string;
 filename: string;
 }
}
export {};
```

构建产物又是另一层坑。用 esbuild 或 tsup 打包后，多个源文件被合并，`import.meta.url` 指向的是产物文件的位置，而不是源码位置。如果代码里靠 `__dirname` 去找相邻的静态资源，打包后路径结构变了就会失效。这种情况下要么把资源路径改成基于包根目录计算，要么在构建配置里保留目录结构，或者用 `import.meta.resolve` 配合包的 `exports` 字段来定位资源。

```js
// 基于包根目录定位，打包后仍然稳定
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const pkgPath = require.resolve('my-lib/package.json');
const pkgRoot = dirname(pkgPath);
```

`createRequire` 还有个别的好处：在 ESM 里需要加载 CommonJS 模块或读取 JSON 时，它能复用 CJS 的解析规则，避免自己拼路径。

最后提一个容易忽略的细节：`import.meta.url` 在通过 `data:` URL 或某些打包器注入的虚拟模块里可能不是 `file:` 协议，此时 `fileURLToPath` 会抛错。如果代码要运行在非文件环境（比如某些边缘运行时），先判断协议再转换：

```js
if (import.meta.url.startsWith('file:')) {
 const dir = dirname(fileURLToPath(import.meta.url));
 // 使用 dir
}
```

迁移时把这几处路径逻辑收敛到一个模块，后续换运行时或调整构建方式都只改一个地方，比在每个文件里零散地补 `fileURLToPath` 要稳得多。

 推荐查看：https://www.52cha.cn/hanzi/16196.html
 推荐查看：https://www.52cha.cn/hanzi/16197.html
 推荐查看：https://www.52cha.cn/hanzi/16198.html
 推荐查看：https://www.52cha.cn/hanzi/16199.html
 推荐查看：https://www.52cha.cn/hanzi/16200.html
 推荐查看：https://www.52cha.cn/hanzi/16201.html
 推荐查看：https://www.52cha.cn/hanzi/16202.html
 推荐查看：https://www.52cha.cn/hanzi/16203.html
 推荐查看：https://www.52cha.cn/hanzi/16204.html
 推荐查看：https://www.52cha.cn/hanzi/16205.html
 推荐查看：https://www.52cha.cn/hanzi/16206.html
 推荐查看：https://www.52cha.cn/hanzi/16207.html
 推荐查看：https://www.52cha.cn/hanzi/16208.html
 推荐查看：https://www.52cha.cn/hanzi/16209.html
 推荐查看：https://www.52cha.cn/hanzi/16210.html
 推荐查看：https://www.52cha.cn/hanzi/16211.html
 推荐查看：https://www.52cha.cn/hanzi/16212.html
 推荐查看：https://www.52cha.cn/hanzi/16213.html
 推荐查看：https://www.52cha.cn/hanzi/16214.html
 推荐查看：https://www.52cha.cn/hanzi/16215.html
 推荐查看：https://www.52cha.cn/hanzi/16216.html
 推荐查看：https://www.52cha.cn/hanzi/16217.html
 推荐查看：https://www.52cha.cn/hanzi/16218.html
 推荐查看：https://www.52cha.cn/hanzi/16219.html
 推荐查看：https://www.52cha.cn/hanzi/16220.html
 推荐查看：https://www.52cha.cn/hanzi/16221.html
 推荐查看：https://www.52cha.cn/hanzi/16222.html
 推荐查看：https://www.52cha.cn/hanzi/16223.html
 推荐查看：https://www.52cha.cn/hanzi/16224.html
 推荐查看：https://www.52cha.cn/hanzi/16225.html
 推荐查看：https://www.52cha.cn/hanzi/16226.html
 推荐查看：https://www.52cha.cn/hanzi/16227.html
 推荐查看：https://www.52cha.cn/hanzi/16228.html
 推荐查看：https://www.52cha.cn/hanzi/16229.html
 推荐查看：https://www.52cha.cn/hanzi/16230.html
 推荐查看：https://www.52cha.cn/hanzi/16231.html
 推荐查看：https://www.52cha.cn/hanzi/16232.html
 推荐查看：https://www.52cha.cn/hanzi/16233.html
 推荐查看：https://www.52cha.cn/hanzi/16234.html
 推荐查看：https://www.52cha.cn/hanzi/16235.html
 推荐查看：https://www.52cha.cn/hanzi/16236.html
 推荐查看：https://www.52cha.cn/hanzi/16237.html
 推荐查看：https://www.52cha.cn/hanzi/16238.html
 推荐查看：https://www.52cha.cn/hanzi/16239.html
 推荐查看：https://www.52cha.cn/hanzi/16240.html
 推荐查看：https://www.52cha.cn/hanzi/16241.html
 推荐查看：https://www.52cha.cn/hanzi/16242.html
 推荐查看：https://www.52cha.cn/hanzi/16243.html
 推荐查看：https://www.52cha.cn/hanzi/16244.html
 推荐查看：https://www.52cha.cn/hanzi/16245.html
 推荐查看：https://www.52cha.cn/hanzi/16246.html
 推荐查看：https://www.52cha.cn/hanzi/16247.html
 推荐查看：https://www.52cha.cn/hanzi/16248.html
 推荐查看：https://www.52cha.cn/hanzi/16249.html
 推荐查看：https://www.52cha.cn/hanzi/16250.html
 推荐查看：https://www.52cha.cn/hanzi/16251.html
 推荐查看：https://www.52cha.cn/hanzi/16252.html
 推荐查看：https://www.52cha.cn/hanzi/16253.html
 推荐查看：https://www.52cha.cn/hanzi/16254.html
 推荐查看：https://www.52cha.cn/hanzi/16255.html
 推荐查看：https://www.52cha.cn/hanzi/16256.html
 推荐查看：https://www.52cha.cn/hanzi/16257.html
 推荐查看：https://www.52cha.cn/hanzi/16258.html
 推荐查看：https://www.52cha.cn/hanzi/16259.html
 推荐查看：https://www.52cha.cn/hanzi/16260.html
 推荐查看：https://www.52cha.cn/hanzi/16261.html
 推荐查看：https://www.52cha.cn/hanzi/16262.html
 推荐查看：https://www.52cha.cn/hanzi/16263.html
 推荐查看：https://www.52cha.cn/hanzi/16264.html
 推荐查看：https://www.52cha.cn/hanzi/16265.html
 推荐查看：https://www.52cha.cn/hanzi/16266.html
 推荐查看：https://www.52cha.cn/hanzi/16267.html
 推荐查看：https://www.52cha.cn/hanzi/16268.html
 推荐查看：https://www.52cha.cn/hanzi/16269.html
 推荐查看：https://www.52cha.cn/hanzi/16270.html
 推荐查看：https://www.52cha.cn/hanzi/16271.html
 推荐查看：https://www.52cha.cn/hanzi/16272.html
 推荐查看：https://www.52cha.cn/hanzi/16273.html
 推荐查看：https://www.52cha.cn/hanzi/16274.html
 推荐查看：https://www.52cha.cn/hanzi/16275.html
 推荐查看：https://www.52cha.cn/hanzi/16276.html
 推荐查看：https://www.52cha.cn/hanzi/16277.html
 推荐查看：https://www.52cha.cn/hanzi/16278.html
 推荐查看：https://www.52cha.cn/hanzi/16279.html
 推荐查看：https://www.52cha.cn/hanzi/16280.html
 推荐查看：https://www.52cha.cn/hanzi/16281.html
 推荐查看：https://www.52cha.cn/hanzi/16282.html
 推荐查看：https://www.52cha.cn/hanzi/16283.html
 推荐查看：https://www.52cha.cn/hanzi/16284.html
 推荐查看：https://www.52cha.cn/hanzi/16285.html
 推荐查看：https://www.52cha.cn/hanzi/16286.html
 推荐查看：https://www.52cha.cn/hanzi/16287.html
 推荐查看：https://www.52cha.cn/hanzi/16288.html
 推荐查看：https://www.52cha.cn/hanzi/16289.html
 推荐查看：https://www.52cha.cn/hanzi/16290.html
 推荐查看：https://www.52cha.cn/hanzi/16291.html
 推荐查看：https://www.52cha.cn/hanzi/16292.html
 推荐查看：https://www.52cha.cn/hanzi/16293.html
 推荐查看：https://www.52cha.cn/hanzi/16294.html
 推荐查看：https://www.52cha.cn/hanzi/16295.html
 推荐查看：https://www.52cha.cn/hanzi/16296.html
 推荐查看：https://www.52cha.cn/hanzi/16297.html
 推荐查看：https://www.52cha.cn/hanzi/16298.html
 推荐查看：https://www.52cha.cn/hanzi/16299.html
 推荐查看：https://www.52cha.cn/hanzi/16300.html
 推荐查看：https://www.52cha.cn/hanzi/16301.html
 推荐查看：https://www.52cha.cn/hanzi/16302.html
 推荐查看：https://www.52cha.cn/hanzi/16303.html
 推荐查看：https://www.52cha.cn/hanzi/16304.html
 推荐查看：https://www.52cha.cn/hanzi/16305.html
 推荐查看：https://www.52cha.cn/hanzi/16306.html
 推荐查看：https://www.52cha.cn/hanzi/16307.html
 推荐查看：https://www.52cha.cn/hanzi/16308.html
 推荐查看：https://www.52cha.cn/hanzi/16309.html
 推荐查看：https://www.52cha.cn/hanzi/16310.html
 推荐查看：https://www.52cha.cn/hanzi/16311.html
 推荐查看：https://www.52cha.cn/hanzi/16312.html
 推荐查看：https://www.52cha.cn/hanzi/16313.html
 推荐查看：https://www.52cha.cn/hanzi/16314.html
 推荐查看：https://www.52cha.cn/hanzi/16315.html
 推荐查看：https://www.52cha.cn/hanzi/16316.html
 推荐查看：https://www.52cha.cn/hanzi/16317.html
 推荐查看：https://www.52cha.cn/hanzi/16318.html
 推荐查看：https://www.52cha.cn/hanzi/16319.html
 推荐查看：https://www.52cha.cn/hanzi/16320.html
 推荐查看：https://www.52cha.cn/hanzi/16321.html
 推荐查看：https://www.52cha.cn/hanzi/16322.html
 推荐查看：https://www.52cha.cn/hanzi/16323.html
 推荐查看：https://www.52cha.cn/hanzi/16324.html
 推荐查看：https://www.52cha.cn/hanzi/16325.html
 推荐查看：https://www.52cha.cn/hanzi/16326.html
 推荐查看：https://www.52cha.cn/hanzi/16327.html
 推荐查看：https://www.52cha.cn/hanzi/16328.html
 推荐查看：https://www.52cha.cn/hanzi/16329.html
 推荐查看：https://www.52cha.cn/hanzi/16330.html
 推荐查看：https://www.52cha.cn/hanzi/16331.html
 推荐查看：https://www.52cha.cn/hanzi/16332.html
 推荐查看：https://www.52cha.cn/hanzi/16333.html
 推荐查看：https://www.52cha.cn/hanzi/16334.html
 推荐查看：https://www.52cha.cn/hanzi/16335.html
 推荐查看：https://www.52cha.cn/hanzi/16336.html
 推荐查看：https://www.52cha.cn/hanzi/16337.html
 推荐查看：https://www.52cha.cn/hanzi/16338.html
 推荐查看：https://www.52cha.cn/hanzi/16339.html
 推荐查看：https://www.52cha.cn/hanzi/16340.html
 推荐查看：https://www.52cha.cn/hanzi/16341.html
 推荐查看：https://www.52cha.cn/hanzi/16342.html
 推荐查看：https://www.52cha.cn/hanzi/16343.html
 推荐查看：https://www.52cha.cn/hanzi/16344.html
 推荐查看：https://www.52cha.cn/hanzi/16345.html
 推荐查看：https://www.52cha.cn/hanzi/16346.html
 推荐查看：https://www.52cha.cn/hanzi/16347.html
 推荐查看：https://www.52cha.cn/hanzi/16348.html
 推荐查看：https://www.52cha.cn/hanzi/16349.html
 推荐查看：https://www.52cha.cn/hanzi/16350.html
 推荐查看：https://www.52cha.cn/hanzi/16351.html
 推荐查看：https://www.52cha.cn/hanzi/16352.html
 推荐查看：https://www.52cha.cn/hanzi/16353.html
 推荐查看：https://www.52cha.cn/hanzi/16354.html
 推荐查看：https://www.52cha.cn/hanzi/16355.html
 推荐查看：https://www.52cha.cn/hanzi/16356.html
 推荐查看：https://www.52cha.cn/hanzi/16357.html
 推荐查看：https://www.52cha.cn/hanzi/16358.html
 推荐查看：https://www.52cha.cn/hanzi/16359.html
 推荐查看：https://www.52cha.cn/hanzi/16360.html
 推荐查看：https://www.52cha.cn/hanzi/16361.html
 推荐查看：https://www.52cha.cn/hanzi/16362.html
 推荐查看：https://www.52cha.cn/hanzi/16363.html
 推荐查看：https://www.52cha.cn/hanzi/16364.html
 推荐查看：https://www.52cha.cn/hanzi/16365.html
 推荐查看：https://www.52cha.cn/hanzi/16366.html
 推荐查看：https://www.52cha.cn/hanzi/16367.html
 推荐查看：https://www.52cha.cn/hanzi/16368.html
 推荐查看：https://www.52cha.cn/hanzi/16369.html
 推荐查看：https://www.52cha.cn/hanzi/16370.html
 推荐查看：https://www.52cha.cn/hanzi/16371.html
 推荐查看：https://www.52cha.cn/hanzi/16372.html
 推荐查看：https://www.52cha.cn/hanzi/16373.html
 推荐查看：https://www.52cha.cn/hanzi/16374.html
 推荐查看：https://www.52cha.cn/hanzi/16375.html
 推荐查看：https://www.52cha.cn/hanzi/16376.html
 推荐查看：https://www.52cha.cn/hanzi/16377.html
 推荐查看：https://www.52cha.cn/hanzi/16378.html
 推荐查看：https://www.52cha.cn/hanzi/16379.html
 推荐查看：https://www.52cha.cn/hanzi/16380.html
 推荐查看：https://www.52cha.cn/hanzi/16381.html
 推荐查看：https://www.52cha.cn/hanzi/16382.html
 推荐查看：https://www.52cha.cn/hanzi/16383.html
 推荐查看：https://www.52cha.cn/hanzi/16384.html
 推荐查看：https://www.52cha.cn/hanzi/16385.html
 推荐查看：https://www.52cha.cn/hanzi/16386.html
 推荐查看：https://www.52cha.cn/hanzi/16387.html
 推荐查看：https://www.52cha.cn/hanzi/16388.html
 推荐查看：https://www.52cha.cn/hanzi/16389.html
 推荐查看：https://www.52cha.cn/hanzi/16390.html
 推荐查看：https://www.52cha.cn/hanzi/16391.html
 推荐查看：https://www.52cha.cn/hanzi/16392.html
 推荐查看：https://www.52cha.cn/hanzi/16393.html
 推荐查看：https://www.52cha.cn/hanzi/16394.html
 推荐查看：https://www.52cha.cn/hanzi/16395.html

把项目从 CommonJS 迁移到 ES 模块时，__dirname 和 __filename 突然不可用是很多人遇到的第一个硬钉子。在 CommonJS 里这两个变量由模块包装函数直接注入，随手拼个相对路径读配置文件、定位静态资源目录都很方便；切换到 type: "module" 或 .mjs 之后，同样的代码直接抛 ReferenceError: __dirname is not defined。这个问题的根源在于 ESM 的模块解析上下文不再提供这两个全局变量，而 import.meta.url 成了新的入口。实际开发中，读取模板、定位证书、计算日志目录、在 CLI 工具里找 package.json 都会踩到它。下面从报错现场出发，把几种可靠的替代写法、跨平台差异和工程里的落地方式讲清楚。

Node.js 中 __dirname 在 ES 模块下的替代方案与路径处理实践

把项目从 CommonJS 迁移到 ES 模块时，__dirname 和 __filename 突然不可用是很多人遇到的第一个硬钉子。在 CommonJS 里这两个变量由模块包装函数直接注入，随手拼个相对路径读配置文件、定位静态资源目录都很方便；切换到 type: "module" 或 .mjs 之后，同样的代码直接抛 ReferenceError: __dirname is not define

编程语言

前端

ESM迁移指南：解决__dirname未定义错误，掌握import.meta.url与fileURLToPath替代方案，区分process.cwd()与模块路径，处理TypeScript类型及打包构建兼容，实现跨平台路径解析。

文件系统

代码解释

TypeScript 

Windows

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Node.js 中 __dirname 在 ES 模块下的替代方案与路径处理实践-腾讯云开发者社区-腾讯云

Node.js 中 __dirname 在 ES 模块下的替代方案与路径处理实践

Node.js 中 __dirname 在 ES 模块下的替代方案与路径处理实践

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐