Vue / 系统课时

配置路径别名

配置路径别名

当组件层级变深时,连续的 ../../../ 会让导入路径难读、难移动。本课把 @ 统一映射到 src,同时配置 Vite 与 TypeScript,并通过启动开发服务器和编辑器提示验证别名是否真正生效。

学习目标

  • 在 Vite 中建立 @ 到 src 的运行时映射
  • 在 TypeScript 中补齐同一套类型解析规则
  • 识别只配置一侧导致的常见报错

统一别名约定

项目只保留一条核心约定:@/ 表示 src/。例如 @/api/user、@/components/AppTable.vue 都从源码根目录开始读取。别名应稳定、数量少,并避免用同一个符号指向不同目录。

配置 Vite

编辑项目根目录的 vite.config.ts。使用 URL 转换获得绝对路径,可以兼容不同操作系统,不需要手写本机路径。

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

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      // 运行时和构建时都把 @/xxx 解析到 src/xxx
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  }
})

保存后,Vite 才能在开发和构建阶段找到 @/ 开头的模块。不要把别名写成当前电脑的绝对路径,否则项目换目录或进入 CI 环境后会失效。

配置 TypeScript

继续编辑 tsconfig.app.json,让类型检查器和编辑器理解同一条映射。paths 只负责类型解析,不会替代 Vite 的运行时配置。

json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": [
    "env.d.ts",
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.vue"
  ]
}

如果项目把前端配置放在其他 tsconfig 文件中,应把 paths 写入实际被应用入口继承的配置,而不是只修改根文件后假设一定生效。

使用并验证

下面的片段示例依赖项目中存在 src/api/user.ts 和 src/components/AppTable.vue,用于确认脚本与 Vue 组件导入都能解析。

ts
import { fetchUsers } from '@/api/user'
import AppTable from '@/components/AppTable.vue'

export { fetchUsers, AppTable }

启动开发服务器:

bash
npm run dev

预期输出:

text
VITE v<version>  ready in <TIME> ms

➜  Local:   http://localhost:<PORT>/

实际版本、耗时和端口可能不同。若终端能启动,但编辑器仍提示“找不到模块”,先重启 TypeScript 服务;若终端直接报无法解析导入,则优先检查 vite.config.ts 的别名、文件名大小写和目标文件是否存在。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置路径别名

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通