告别烦人的相对路径：Vite + VSCode 路径别名配置全指南

在日常的前端开发中 ，我们经常遇到这样的场景：当项目目录嵌套较深时，组件之间的相互引用就会变成一场灾难 。满屏的 ./../../components/Button 不仅让代码看起来杂乱无章，一旦后续调整了文件层级，还需要手动去修改无数个相对路径 。

为了解决这个问题，我们通常会配置 路径别名（Path Alias） ，比如使用 @/ 来代替 src/。但在纯 JavaScript 项目中，很多开发者发现：明明在 Vite 里配置好了别名，为什么 VSCode 自动导入时依然会生成一长串的相对路径？

其实，这是因为你只走了一半的路 ‍。要让别名完美生效，必须同时搞定“构建工具”和“编辑器”这两套系统 ️。

核心原理：为什么需要双重配置？

要彻底解决这个问题，首先要理解这两个配置文件分别服务于谁 ：

1. vite.config.js —— 给构建工具看：它的作用是在项目启动、打包和运行时，告诉 Vite 遇到 @/ 就去 src 目录下找文件。如果不配这个，代码跑起来就会报错找不到模块 。

2. ️ jsconfig.json —— 给 VSCode 看：VSCode 的智能感知（包括自动导入、代码补全、跳转）底层依赖的是 TypeScript 语言服务。它完全不读 Vite 的配置文件 ‍。只有显式地写了 jsconfig.json，VSCode 才知道路径别名是什么，从而为你提供正确的提示 。

简单来说：Vite 负责让项目“能跑” ‍，而 jsconfig.json 负责让你在写代码时“用得爽” 。

️ 实战操作：纯 JS 项目的正确配置姿势

第一步：配置 Vite 运行环境

在你的 vite.config.js 中推荐使用官方脚手架标准的 fileURLToPath 写法，它不仅更符合 ESM 规范，而且跨平台兼容性极佳：

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { fileURLToPath, URL } from 'node:url';

export default defineConfig({
    plugins: [vue()],
    // 路径别名配置
    resolve: {
        alias: {
            '@': fileURLToPath(new URL('./src', import.meta.url)),
        },
    },
});

第二步：配置 VSCode 智能感知（关键！）

在项目根目录（与 package.json 同级）新建或修改 jsconfig.json 文件，填入以下基础模板：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

配置细节解析：

• "baseUrl": "."：这是必须的基准地址，告诉 VSCode 以当前项目根目录作为计算路径的起点，否则 paths 里的别名可能无法生效。

• "@/*": ["src/*"]：键是你代码里使用的别名前缀，值是实际对应的物理目录。注意两边都要带上 /* 通配符。

• exclude：强烈建议把 node_modules 和构建产物（如 dist）排除掉。这能避免语言服务扫描大量无关文件，让自动导入响应变得更快。

第三步：重启语言服务

修改完配置文件后，VSCode 往往不会立即生效，因为存在缓存 。你必须强制刷新语言服务：

1. 按下快捷键 Ctrl + Shift + P（Mac 为 Cmd + Shift +P）️。

2. 输入并选择：TypeScript: Restart TS server。

完成以上三步后 ，你的 VSCode 就能完美识别 @/ 别名了！以后无论是敲下 @/ 触发补全，还是使用自动导入功能，都会乖乖使用优雅的路径别名，并且支持 Ctrl+Click 丝滑跳转 。