TypeScript与Vite路径别名配置详解：为何需在tsconfig和vite中重复设置

在前端工程化项目中，使用TypeScript和Vite时，开发者常遇到一个困惑：为什么在tsconfig.json中已经配置了路径别名，还需要在vite.config.ts中再次配置？这看似重复的操作，实则源于工具链的分工差异。

路径别名的双重配置原因

tsconfig.json中的路径别名配置，如以下示例，是专为TypeScript编译器服务的：

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

当你在代码中写入import xx from '@api/user'时，TypeScript编译器会基于此配置进行类型检查和IDE提示，确保开发时语法正确。然而，这仅解决了“写代码”阶段的路径识别问题。

Vite作为现代构建工具，在运行开发服务器、进行依赖预构建或最终打包时，并不直接读取tsconfig.json。Vite依赖自己的解析器来处理模块路径，因此必须在vite.config.ts中明确声明别名，否则运行时将报错“找不到模块”。配置示例如下：

// vite.config.ts
import { defineConfig } from 'vite'
import path from 'path'

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

简单来说，tsconfig.json负责TypeScript编译时的路径校验，而vite.config.ts负责构建和运行时的路径解析。两者各司其职，缺一不可。

自动同步的解决方案

为避免手动维护两份配置，可以使用插件如vite-tsconfig-paths来自动同步。安装后，在Vite配置中引入即可：

npm i vite-tsconfig-paths -D

// vite.config.ts
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [tsconfigPaths()]
})

这样，Vite会自动读取tsconfig.json中的paths配置，减少重复劳动。但需注意，某些场景下TypeScript和Vite的路径解析需求可能不完全一致，因此显式配置两处仍是推荐做法，以确保兼容性和清晰性。

总结：路径别名的三个阶段

1. TypeScript识别：开发时校验和IDE提示，依赖tsconfig.json。
2. Vite识别：开发服务器解析和依赖预构建，依赖vite.config.ts。
3. 打包工具识别：最终构建由Rollup处理，同样通过vite.config.ts中的alias配置。

因此，若只配置tsconfig.json，代码编写时无报错，但运行会失败；若只配置vite.config.ts，代码可能通过运行，但IDE会显示路径错误。最佳实践是两者都配置，或使用插件自动同步，以提升开发效率和项目可维护性。