你有没有写TypeScript项目时，导入工具函数要写三四个点的相对路径，找半天都没看清到底导入的是哪的文件？或者突然遇到模块循环引用的报错，半天找不到问题在哪？其实这些大多和你对TS模块系统的理解不足有关，今天就从最基础的模块概念讲起，带你梳理TS模块的核心逻辑，再一步步优化项目结构，让代码更清爽好维护。

一、TS模块系统的核心概念：别把模块当“代码打包”

1.1 CommonJS和ES模块：不是谁取代谁，是各有适用场景

很多人刚接触TS时，会纠结为什么有时候用require，有时候用import。其实这是JS（TS完全兼容）的两种模块规范：CommonJS是Node.js早期的模块方案，用require导入、module.exports导出；ES模块是后来的官方标准，用import/export，支持静态分析，打包体积更小。TS默认会转译CommonJS，你可以在tsconfig.json里把module设为ESNext，就能启用原生ES模块了。举个简单的例子：

// 这是CommonJS规范的工具模块，常用于Node.js环境
const { add } = require('./utils');
console.log(add(1, 2)); // 输出3

// 这是ES模块规范的工具模块，前端项目更常用
export function add(a: number, b: number): number {
  return a + b;
}
// 导入ES模块的方式
import { add } from './utils';
console.log(add(1, 2)); // 输出3

1.2 TS的模块解析规则：别让配置坑了你

TS找模块的方式叫“模块解析”，核心配置在tsconfig.json里。比如baseUrl设为.，就是以项目根目录为基准找模块；moduleResolution选node，就按Node.js的规则查找依赖。很多时候导入报错，就是这里配置错了——比如设了baseUrl但没配路径别名，或者别名映射写错了。

二、项目混乱的元凶：你可能踩了这些模块的坑

2.1 相对路径太深：从../写到吐

比如你在src/pages/user/edit.ts里，要导入src/utils/date.ts，相对路径要写../../../utils/date，不仅麻烦还容易写错，万一移了一个文件的位置，所有路径都要改，简直是噩梦。我刚写TS项目的时候就踩过这个坑，改了页面位置，半天找不到哪个导入错了。

2.2 循环引用：两个模块互相导入的死循环

还有一种坑是循环引用，比如a.ts导入b.ts，b.ts又导入a.ts，TS编译时会报错说“找不到xxx的导出”。这是因为模块加载顺序的问题，TS要保证导入的内容存在，但循环引用会让加载顺序混乱，导致变量还没定义就被引用了。

三、项目结构优化实践：告别模块混乱

3.1 路径别名：用@代替长长的相对路径

解决相对路径深的核心方法是配置路径别名。你可以在tsconfig.json里设baseUrl为.，再配paths让@/*指向src/*，这样导入时只要写@/utils/date，不管在哪个目录都能精准找到文件。如果用Vite、Webpack这些构建工具，还要在构建配置里也加对应别名，不然开发时会报模块找不到，比如Vite的配置：

import { defineConfig } from 'vite';
// Vite配置里加别名，和tsconfig的paths对应
export default defineConfig({
  resolve: {
    alias: {
      '@': '/src'
    }
  }
});

3.2 合理拆分模块：给每个模块定好职责

模块混乱的另一个原因是职责不清，比如把组件、工具函数、页面都混在一个目录。合理的拆分应该按功能来，比如src下分components（通用可复用组件，如按钮、输入框）、pages（页面级组件，每个页面一个目录）、utils（通用工具函数，如日期格式化）、types（全局类型定义，如用户、订单类型）。这样导入时一看路径就知道模块用途，团队协作时不用反复问人。

3.3 类型导出：用TS的优势减少冗余

TS最大的优势是类型，导入时可以只导入类型，不用导入实际函数，比如import type { User } from '@/types/user'，这样打包时不会把类型打进去，减少代码体积，还能一眼区分“用的是类型还是实际功能”，让代码更清晰。

四、优化的实际价值与注意事项

4.1 应用场景

这些优化技巧适合所有TS项目：小型工具库用路径别名能减少路径错误，大型管理系统用合理拆分能提升团队协作效率，不管新手老手都能快速上手。

4.2 技术优缺点

路径别名的优点是可读性高、减少路径错误；缺点是需要两边配置（tsconfig和构建工具），配置错了容易出问题。合理拆分模块的优点是可维护性强；缺点是拆分过细可能增加新人的学习成本。

4.3 注意事项

配置别名时，baseUrl要设对（设成.是项目根目录，别设成src）；构建工具的别名必须和tsconfig的paths完全一致，不然开发时会报错；循环引用一定要避免，可抽离公共函数到单独的common模块。

五、总结

TS模块系统的核心是理解不同模块规范的适用场景，通过路径别名、合理拆分模块、类型导出这些技巧，能彻底告别模块混乱的问题，提升代码可读性和维护性。不管你是刚学TS的新手，还是写了很久的老手，掌握这些技巧都能减少踩坑，提升开发效率。