TypeScript 路径别名“Cannot find module”报错：从根因到生产环境根治方案

TypeScript 的路径别名（paths 配置）能极大改善代码可读性，避免 ../../../utils 这样的“面条路径”。但几乎所有开发者都踩过这个坑：tsconfig.json 里配好了 paths，IDE 里类型检查也通过了，一运行就报 Cannot find module。

本文直接拆解这个问题的根因，并给出从开发到生产环境的完整解决方案，涵盖 ts-node、Jest、Webpack 等常见场景。

它解决什么问题：为什么 tsc 编译后路径别名会失效？

TypeScript 编译器（tsc）只负责类型检查和语法转译。它不会将 tsconfig.json 中的 paths 映射转换为运行时 Node.js 能理解的模块路径。

举个例子，你的代码里写了：

TYPESCRIPT
import { helper } from '@utils/helper';

tsc 编译后，输出的 .js 文件中仍然是 @utils/helper。Node.js 不认识这个路径，自然报错。

所以，路径别名问题的本质是：你需要一个额外的运行时或构建时工具，来告诉 Node.js 或打包器如何解析这些自定义路径。

核心配置与参数说明：四种主流解决方案

下表对比了最常用的四种方案，请根据你的项目技术栈选择。

关键提醒：无论选择哪种方案，务必确保 tsconfig.json 中的 baseUrl 和 paths 配置正确。baseUrl 是路径解析的根目录，例如：

JSON
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

常见报错与排查：针对具体场景的解决步骤

错误 1：Cannot find module '@shared/utils' — 运行时 Node.js 报错

根因：没有加载运行时路径解析器。

解决步骤：

1. 安装 tsconfig-paths：

   BASH
   npm install tsconfig-paths
   

2. 在入口文件最顶部加载（必须在任何业务代码之前）：

   TYPESCRIPT
   // index.ts 或 app.ts 的第一行
   require('tsconfig-paths/register');
   

   或者使用 --require 参数启动：

   BASH
   node -r tsconfig-paths/register dist/index.js
   

3. 如果使用 ts-node，可以配置 tsconfig.json 的 ts-node 字段：

   JSON
   {
     "ts-node": {
       "files": true,
       "require": ["tsconfig-paths/register"]
     }
   }
   

错误 2：Module not found: Error: Can't resolve '@/components/Button' — Webpack 构建报错

根因：Webpack 不知道 @ 指向哪里。

解决步骤： 在 webpack.config.js 中配置 resolve.alias，并确保与 tsconfig.json 的 paths 一致：

JAVASCRIPT
const path = require('path');

module.exports = {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@utils': path.resolve(__dirname, 'src/utils'),
    },
  },
};

错误 3：Jest 测试中 Cannot find module '@utils/helper'

根因：Jest 使用 Node.js 的模块解析机制，不识别 tsconfig 的 paths。

解决步骤： 在 jest.config.js 中配置 moduleNameMapper：

JAVASCRIPT
module.exports = {
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
    '^@utils/(.*)$': '<rootDir>/src/utils/$1',
  },
};

如果使用 ts-jest，可以自动映射：

JAVASCRIPT
const { pathsToModuleNameMapper } = require('ts-jest');
const { compilerOptions } = require('./tsconfig.json');

module.exports = {
  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: '<rootDir>/' }),
};

错误 4：TypeError: Cannot read properties of undefined (reading 'paths')

根因：tsconfig.json 中缺少 baseUrl 或 paths 配置格式错误。

解决步骤：

1. 确保 compilerOptions 中同时包含 baseUrl 和 paths。
2. 检查 paths 的键值对格式，例如 "@/*": ["src/*"] 中的 * 是通配符，不能省略。
3. 升级 tsconfig-paths 到最新版，确保与 TypeScript 版本兼容。

常见问题 FAQ

Q: 为什么 tsconfig.json 中配置了 paths，但 Node.js 直接运行编译后的 JS 文件仍然找不到模块？

A: TypeScript 编译器（tsc）不会自动将 tsconfig paths 转换为运行时模块解析逻辑。tsc 仅用于类型检查，编译后的 JS 文件中的路径别名仍然是原始别名（如 @shared/utils），Node.js 无法识别。解决方案：1) 使用 tsconfig-paths/register 在运行时动态解析；2) 使用 module-alias 手动注册别名；3) 使用打包工具（Webpack、Vite）的 resolve.alias 功能；4) 使用 tsc-alias 插件在编译后自动替换路径。

Q: 在 monorepo 项目中，如何让多个包的路径别名统一生效？

A: 在 monorepo 中，建议在根目录 tsconfig.base.json 中定义公共 paths，然后每个子包的 tsconfig.json 通过 extends 继承。运行时，使用 tsconfig-paths 时需指定正确的 tsconfig 文件路径（--project 参数）。如果使用 Lerna 或 Nx，可配置全局的 moduleNameMapper（Jest）或 resolve.alias（Webpack）。注意：不同包之间的路径别名可能冲突，建议使用统一的命名空间前缀（如 @myorg/）。

Q: 使用 ts-node 时，如何确保路径别名在开发和生产环境都正常工作？

A: 开发环境：在 tsconfig.json 中添加 'ts-node' 字段，设置 'files': true，并确保 tsconfig-paths/register 已加载。生产环境：建议使用 tsc 编译后，配合 tsc-alias 插件自动替换路径别名，或使用 module-alias 在运行时注册。最佳实践：统一使用打包工具（如 esbuild、Webpack）处理路径别名，避免运行时依赖。

生产环境实践与注意事项

1. 避免运行时解析开销：生产环境推荐使用 tsc-alias 或打包工具的 resolve.alias，将路径别名在构建时替换为真实路径，避免每次启动都进行动态解析。
2. 保持配置一致性：tsconfig.json、webpack.config.js、jest.config.js 中的路径映射必须完全一致。建议使用脚本或工具（如 ts-jest 的 pathsToModuleNameMapper）自动同步。
3. 安全性注意：避免将路径别名指向敏感目录（如 /etc、/root），防止模块注入攻击。路径别名应严格限制在项目源码目录内。
4. Monorepo 跨包问题：如果多个包共享路径别名，确保每个包的 tsconfig.json 都正确 extends 公共配置，并且运行时工具（如 tsconfig-paths）能正确找到对应的 tsconfig 文件。
5. 并发冲突：多个进程同时使用同一 tsconfig 文件时，需确保文件锁定机制（如使用 fs 的 flock）防止配置读取冲突。这在 CI/CD 流水线中尤其需要注意。

注意：本文中的具体版本号、性能数字等细节请以官方文档为准。相关工具的最新文档可参考：

• tsconfig-paths
• module-alias
• tsc-alias