TypeScript 模块问题：模块解析失败与路径别名

开发 TypeScript 项目时，你是否遇到过 Cannot find module '@/components/Button' 或 TS2307: Error 这样的报错？这通常是因为 TypeScript 无法识别你定义的简短路径别名。解决这个问题需要分两步走：先让 TypeScript 编译器认识它，再让运行时（如 Node.js 或打包工具）找到它。

以下步骤将带你彻底解决模块解析失败的问题，实现从丑陋的 ../../../ 到优雅的 @/ 的转变。

第一阶段：配置 TypeScript 编译器

TypeScript 默认只支持相对路径（如 ./utils）和 Node 模块路径（如 lodash）。要让 @/ 这样的别名生效，必须修改 tsconfig.json。

1. 打开项目根目录下的 tsconfig.json 文件。
2. 定位到 compilerOptions 对象内部。
3. 添加或修改 baseUrl 字段。该字段指定了模块解析的根目录。对于大多数项目，通常设置为 "."（表示当前根目录）或 "./src"。
4. 添加 paths 字段。这是一个键值对对象，键是你要匹配的模式，值是实际要跳转的路径数组。

配置示例如下：

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

注意：paths 里的路径是相对于 baseUrl 的。如果 baseUrl 是 "."，那么 "src/*" 就指向根目录下的 src 文件夹。

第二阶段：理解解析流程

为什么配置完 tsconfig.json 后，编辑器不报错了，但运行项目时还是会崩？因为 tsconfig.json 仅作用于 TypeScript 编译器的类型检查阶段。当代码运行在 Node.js 或浏览器中时，它们根本不认识 @/ 是什么。

下图展示了代码从编写到运行过程中，模块解析的流向：

要消除运行时的错误，必须根据你使用的工具进行额外配置。

第三阶段：配置构建工具与运行时

根据项目技术栈的不同，你需要选择以下对应的方案进行操作。

场景一：使用 Vite

Vite 是目前最流行的构建工具之一。

1. 打开项目根目录下的 vite.config.ts 文件。
2. 导入 path 模块（Node.js 内置模块）。
3. 在 defineConfig 函数中，配置 resolve.alias 字段。

import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

场景二：使用 Webpack

React Create App 或自定义 Webpack 项目通常需要此步骤。

1. 打开 webpack.config.js 文件。
2. 引入 path 模块。
3. 找到 resolve.alias 配置项并添加别名规则。

const path = require('path');

module.exports = {
  // ...其他配置
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
};

场景三：使用 Jest 进行测试

单元测试环境是路径别名问题的重灾区。

1. 打开 jest.config.js 或 package.json 中的 jest 字段。
2. 配置 moduleNameMapper 字段。这里需要使用正则表达式来匹配路径。

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

场景四：使用 Node.js (ts-node)

如果你直接用 ts-node 运行服务端代码，Node.js 本身不支持 TypeScript 的路径映射。

1. 安装 tsconfig-paths 包。
2. 运行代码时，使用 -r 参数注册该模块。

在终端中执行：

node -r tsconfig-paths/register src/index.ts

或者在 package.json 的 scripts 中修改启动命令：

{
  "scripts": {
    "dev": "node -r tsconfig-paths/register src/index.ts"
  }
}

第四阶段：常见陷阱排查

如果完成上述所有步骤后仍然报错，请逐一检查以下事项。

1. 检查文件扩展名。
   TypeScript 允许在导入语句中省略 .ts 或 .tsx 后缀，但某些运行时配置（如 Jest 或 Webpack 的旧版本）可能要求在正则或配置中显式处理扩展名。

2. 检查大小写敏感。
   在 Windows 和 macOS 系统上，文件路径默认不区分大小写，但在 Linux 服务器或严格模式的构建工具中，@/Utils 和 @/utils 是两个不同的路径。确保 import 语句中的大小写与实际文件夹名称完全一致。

3. 重启开发服务器。
   修改配置文件（如 vite.config.ts 或 tsconfig.json）后，必须彻底停止并重启终端中的服务进程（Ctrl + C 然后重新运行），配置才会生效。

不同环境下的配置位置汇总如下表：