以下是配置 Vite 项目中使用 @ 路径别名的完整指南：

在 Vite 项目中配置 `@` 路径提示

通过配置路径别名，可以简化模块导入路径，提升代码可读性。以下是详细步骤：

1. 安装 Node.js 类型声明

确保 TypeScript 能识别 Node.js 的 path 模块：

npm install -D @types/node

2. 配置 Vite 路径解析

修改 vite.config.ts，添加路径别名：

import { defineConfig } from 'vite'
import path from 'path'
import { fileURLToPath } from 'url'
import react from '@vitejs/plugin-react'

// 获取当前文件目录路径
const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'), // 精确指向 src 目录
    },
  },
})

关键点说明

使用 fileURLToPath 和 import.meta.url 获取 ESM 模块的物理路径
path.resolve 确保在不同操作系统下路径解析一致

3. 配置 TypeScript 路径映射

更新 tsconfig.json 使 TypeScript 识别别名：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
    // 其他配置保持不变...
  },
  "include": ["src"]
}

4. (可选) 配置 ESLint 路径解析

安装依赖：

npm install -D eslint-plugin-import

更新 .eslintrc.js：

module.exports = {
  settings: {
    'import/resolver': {
      alias: {
        map: [['@', './src']],
        extensions: ['.ts', '.tsx', '.js', '.jsx'], // 支持的文件扩展名
      },
    },
  },
}

5. 验证路径别名

在组件中使用新路径：

// src/components/Button.tsx
import Icon from '@/assets/icon.svg' // 实际路径: src/assets/icon.svg

常见问题排查

Vite 服务器未重启
修改配置后需重启开发服务器
IDE 缓存未更新
VS Code 可执行 > TypeScript: Restart TS Server
路径大小写敏感
Linux 系统需确保实际路径大小写与引用完全一致

配置原理

工具	作用	关联文件
Vite	构建时路径解析	vite.config.ts
TypeScript	编码时类型检查和路径提示	tsconfig.json
ESLint	代码规范校验	.eslintrc.js

通过以上配置，你的项目将获得：

✅ 简洁的路径导入语法
✅ 跨平台路径解析支持
✅ 完整的 IDE 智能提示
✅ 规范的代码校验体系

最佳实践建议：

将高频访问目录设为别名（如 @components, @utils）
在项目文档中维护别名目录结构说明
使用 path.resolve 代替字符串拼接确保路径安全

// 扩展多别名示例
alias: {
  '@': path.resolve(__dirname, 'src'),
  '@components': path.resolve(__dirname, 'src/components')
}