前端 import.meta.dirname 怎么替代路径拼接：Node.js ESM 文件定位、兼容边界与构建发布

在 Node.js 的 ESM 文件里，过去我们常用 fileURLToPath(import.meta.url) 再配合 path.dirname() 模拟 CommonJS 的 __dirname。较新的 Node.js 已提供 import.meta.dirname 和 import.meta.filename，但它们不是浏览器标准，也不是所有构建产物都能原样保留。真正稳妥的做法，是先分清“需要文件系统路径”还是“只需要相对模块资源”，再按运行时版本选择写法。

先判断：你要的是路径字符串，还是模块旁边的资源

这两个需求经常被混在一起。脚本需要把日志目录交给只接受字符串的第三方库时，确实需要一个文件系统路径；而读取模板、证书或 JSON 配置时，很多 Node.js 文件 API 可以直接接收 URL 对象。后者没有必要先把 URL 拆成字符串再拼回路径。

import { readFile } from 'node:fs/promises';

// 资源和当前模块绑定，不依赖 process.cwd()
const configUrl = new URL('./config/default.json', import.meta.url);
const config = JSON.parse(await readFile(configUrl, 'utf8'));

process.cwd() 表示启动命令所在目录，不表示当前模块所在目录。测试框架、工作区脚本和生产进程经常从不同目录启动，因此用工作目录拼接项目资源，往往在本地能跑、发布后才暴露问题。

新 Node.js 中直接使用 import.meta.dirname

如果目标运行时已经支持该属性，下面的写法最接近 CommonJS 的使用习惯：

import path from 'node:path';
import { fileURLToPath } from 'node:url';

console.log(import.meta.dirname);
console.log(import.meta.filename);

const cacheDir = path.join(import.meta.dirname, 'cache');
const currentFile = import.meta.filename;

Node.js 官方文档将 import.meta.dirname 定义为当前模块目录名，它等价于 path.dirname(import.meta.filename)；import.meta.filename 是解析符号链接后的绝对文件路径。两者的限制也要一起记住：只有 file: 模块提供这两个属性，虚拟模块或其他协议不能假定存在。

这套 API 适合需要字符串路径的场景，例如把目录传给只接受路径的旧库、构造缓存位置，或将路径写进调试信息。若只是读取旁边的文件，仍可以优先使用 URL 对象，让资源关系更明确。

旧版兼容写法：fileURLToPath 比 pathname 更可靠

项目需要支持 Node.js 20.10 或更早版本时，可以保留下面的兼容函数：

import path from 'node:path';
import { fileURLToPath } from 'node:url';

const currentFile = fileURLToPath(import.meta.url);
const currentDir = path.dirname(currentFile);
const templatePath = path.join(currentDir, 'templates', 'index.html');

不要简单写成 new URL('./templates/index.html', import.meta.url).pathname。URL 的 pathname 仍是 URL 语义，带空格、非 ASCII 字符或 Windows 盘符时，直接当作 Node.js 文件路径会留下编码和平台差异。fileURLToPath() 会处理百分号编码，并返回当前平台可用的绝对路径。

如果调用方本身接受 URL，兼容代码可以更短：

import { readFile } from 'node:fs/promises';

const templateUrl = new URL('./templates/index.html', import.meta.url);
const template = await readFile(templateUrl, 'utf8');

一个小型兼容层：只在需要时转成字符串

公共库通常不能假定调用者使用的 Node.js 主版本。可以把能力检测集中起来，但不要在模块加载时访问不存在的属性：

import path from 'node:path';
import { fileURLToPath } from 'node:url';

const dirname = import.meta.dirname ??
  path.dirname(fileURLToPath(import.meta.url));

export function siblingPath(...parts) {
  return path.join(dirname, ...parts);
}

这里的回退只解决 Node.js 本地 ESM 运行时。它不等于“浏览器和任意打包器都支持目录名”。如果代码会被送进浏览器，应该把资源交给打包器的导入机制，或者把资源路径作为构建配置注入，不要把 Node.js 文件系统路径暴露给浏览器代码。

构建和发布时最容易踩的三个边界

边界一：运行 Node.js 版本和本地开发版本不一致

本机使用较新的 Node.js 时，import.meta.dirname 可以正常运行；CI 或服务器仍可能是旧版本。把 engines.node、容器基础镜像和 CI 矩阵写成同一条事实，并在发布检查中打印 process.version，比只看本机测试更可靠。

边界二：打包器把模块变成单文件或虚拟模块

Node.js 直接运行源文件时，模块 URL 通常对应真实的 file: 文件。经过打包后，代码可能被合并到一个输出文件，资源可能被复制到新的目录，也可能被内联。此时 import.meta.dirname 代表的是打包产物位置，未必还是源码目录。构建配置应明确资源是“随包复制”还是“运行时外置”，并在产物目录中检查实际文件是否存在。

边界三：把 URL 和路径字符串混用

readFile() 可以接收 URL，但第三方库可能只认字符串。不要在每个调用点随意使用 String(url) 或 url.pathname；把转换放在适配层，统一使用 fileURLToPath()，并让函数名体现它返回的是路径还是 URL。

用最小验收脚本确认发布产物

在构建目录中放一份相邻资源，分别用新 API、兼容回退和 URL 读取做验收，可以尽早发现“源码能跑、产物找不到文件”的问题：

import { access, readFile } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const dir = import.meta.dirname ??
  path.dirname(fileURLToPath(import.meta.url));
const resourceUrl = new URL('./assets/health.json', import.meta.url);

await access(path.join(dir, 'assets', 'health.json'));
const health = JSON.parse(await readFile(resourceUrl, 'utf8'));

if (health.ready !== true) {
  throw new Error('发布产物资源未就绪');
}
console.log('resource-check: ok');

验收应在最终输出目录执行，而不是只在源码目录执行。若应用使用容器，还要用与生产相同的用户、工作目录和启动命令运行一次。这样检查的是实际交付物，不是开发机上的偶然路径。

常见问题

import.meta.dirname 是浏览器标准吗？

不是。它是 Node.js ESM 提供的运行时属性；浏览器中的 import.meta.url 有标准语义，但浏览器没有 Node.js 文件系统目录这一层概念。

什么时候仍然应该使用 fileURLToPath？

当项目需要支持尚未提供该属性的 Node.js 版本，或代码需要把模块 URL 转成路径字符串交给旧库时，继续使用它最稳妥。

new URL('./file', import.meta.url) 能替代所有 path.join 吗？

不能。它适合以当前模块为基准解析资源 URL；需要拼接用户输入、执行路径规范化或调用只接受字符串路径的库时，仍应使用 path 和 fileURLToPath，并做好输入边界检查。

为什么源码中存在文件，打包后却找不到？

打包器改变了模块位置或资源复制策略。检查最终产物旁边是否有目标文件，并确认代码里的相对引用是相对产物、源码还是工作目录；三者不是同一个基准。

把路径基准写进工程约定

对于 Node.js ESM 项目，可以把规则收敛成三句话：模块相邻资源优先用 new URL()；必须交给路径型 API 时用 import.meta.dirname 或 fileURLToPath()；构建发布后在产物目录执行资源验收。这样既能利用新 API，又不会把某个本地 Node.js 版本或启动目录的假设带进生产环境。