Vite+React+TypeScript模板中导入别名配置不生效问题

问题背景 #

在Vite React模板中安装shadcn/ui后，编译器无法识别@/*形式的导入别名。项目包含三个TypeScript配置文件：tsconfig.json、tsconfig.app.json、tsconfig.node.json，最初主tsconfig.json未定义compilerOptions，将该配置复制到主文件并添加别名规则后问题仍未解决。

当前配置 #

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "files": [],
  "references": [
    {
      "path": "./tsconfig.app.json"
    },
    {
      "path": "./tsconfig.node.json"
    }
  ]
}

vite.config.ts

import path from "path";
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

报错截图 #

解决方案 #

Vite React模板采用TypeScript项目引用结构，主tsconfig.json仅用于关联子配置，实际应用代码的TS校验依赖tsconfig.app.json，因此需要调整配置位置：

1. 将别名配置移至tsconfig.app.json
   修改tsconfig.app.json，在compilerOptions中添加baseUrl和paths（保留原有其他配置）：

   // tsconfig.app.json
   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "@/*": ["./src/*"]
       },
       "target": "ES2020",
       "useDefineForClassFields": true,
       "lib": ["ES2020", "DOM", "DOM.Iterable"],
       "module": "ESNext",
       "skipLibCheck": true,
       // 保留原有其他配置项
     },
     "include": ["src"],
     "references": [{ "path": "./tsconfig.node.json" }]
   }
   

2. 恢复主tsconfig.json结构
   移除主tsconfig.json中的compilerOptions，回到项目引用的初始结构：

   // tsconfig.json
   {
     "files": [],
     "references": [
       {
         "path": "./tsconfig.app.json"
       },
       {
         "path": "./tsconfig.node.json"
       }
     ]
   }
   

3. 重启TypeScript服务或编辑器
   修改配置后，执行以下操作清除缓存：

   • 在VS Code中按Ctrl+Shift+P（Windows）/Cmd+Shift+P（Mac），选择「TypeScript: Restart TS Server」
   • 若仍未生效，重启编辑器

原理说明 #

主tsconfig.json作为项目引用的入口文件，本身不参与实际代码的编译校验，仅用于关联tsconfig.app.json（应用代码配置）和tsconfig.node.json（Node端代码配置）。别名规则必须定义在实际生效的子配置文件中，才能被TypeScript编译器和编辑器识别。

内容的提问来源于stack exchange，提问作者DigitNerd