SWC-Node 项目中路径解析问题的深度解析与解决方案

问题背景

在基于 SWC-Node 的现代 JavaScript/TypeScript 项目中，开发者经常会遇到模块路径解析的问题，特别是在复杂的 monorepo 结构中。当项目采用 ESM (ECMAScript Modules) 模式（即 package.json 中设置 "type": "module"）时，路径解析问题尤为突出。

问题现象

在 monorepo 结构中，当尝试通过 @swc-node/register 在 ESM 环境下运行时，SWC 编译器会出现路径解析错误。具体表现为：

1. 编译器会错误地在路径中添加大量 ../../../ 前缀
2. 跨包的模块引用无法正确解析
3. 项目内部的路径别名（如 @app/*）无法正常工作

技术分析

根本原因

这个问题的核心在于 SWC 编译器在处理路径别名和项目引用时的行为差异。当项目采用 ESM 模式时，Node.js 对模块解析有更严格的要求，而 SWC 的路径转换逻辑与 Node.js 的 ESM 解析器之间存在不匹配。

关键配置因素

1. tsconfig.json 的配置：特别是 baseUrl 和 paths 的设置
2. 项目引用（Project References）：在多包项目中正确设置项目间的依赖关系
3. SWC 配置：.swcrc 文件中的模块解析相关设置

解决方案

正确配置 tsconfig.json

1. baseUrl 设置：确保 baseUrl 正确指向项目根目录
2. paths 映射：精确配置路径别名映射
3. 项目引用：必须显式声明对其他项目的引用

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app/*": ["../apps/bar/*"]
    }
  },
  "references": [
    {
      "path": "../apps/bar/tsconfig.json"
    }
  ]
}

避免使用 .swcrc

在已有 tsconfig.json 的情况下，可以完全省略 .swcrc 文件，让 @swc-node 直接从 tsconfig.json 读取配置。这样可以避免配置冲突和优先级问题。

项目结构建议

1. 明确项目边界：每个子项目应有清晰的边界和独立的 tsconfig.json
2. 统一路径解析策略：在整个 monorepo 中使用一致的路径解析规则
3. 合理使用项目引用：对于跨项目依赖，必须使用 TypeScript 的项目引用功能

最佳实践

1. 单一配置源：优先使用 tsconfig.json 而非 .swcrc
2. 完整路径声明：在项目引用中指定完整的 tsconfig.json 路径
3. 环境一致性：确保开发环境和构建环境使用相同的路径解析逻辑
4. 渐进式迁移：对于大型项目，可以逐步迁移到正确的路径解析方案

总结

SWC-Node 在 ESM 环境下的路径解析问题主要源于配置不当和项目引用缺失。通过正确配置 tsconfig.json 的项目引用和路径映射，可以解决大多数路径解析问题。对于复杂的 monorepo 项目，合理规划项目结构和依赖关系是确保模块解析正常工作的关键。

理解这些原理和解决方案后，开发者可以更自信地在 ESM 环境下使用 SWC-Node 构建复杂的 JavaScript/TypeScript 应用程序。