前端工程化 / 系统课时

配置路径别名

配置路径别名

本课解决深层相对路径难读、移动文件后易失效的问题。你将同时配置 Vite 的运行时解析和 TypeScript 的编辑器解析,让 @/utils/format 在开发、类型检查与生产构建中指向同一个文件。

学习目标

  • 使用 resolve.alias 把稳定前缀映射到项目目录
  • 在 TypeScript 配置中声明相同的 paths
  • 通过类型检查和生产构建验证两套解析结果一致

先认识两套路径解析

编辑器中的跳转、补全和类型检查由 TypeScript 解析器负责;开发服务器与生产构建由 Vite 解析器负责。只改一侧时,常见现象是“编辑器报红但页面能运行”,或“编辑器正常但构建提示找不到模块”。

路径别名的双重解析关系

Vite 的文件系统别名应使用绝对路径;相对替换值不会自动转换为文件系统绝对路径。:contentReference[oaicite:0]{index=0}

配置同一个别名

在现有 Vite + TypeScript 项目的 vite.config.ts 中配置运行时别名。fileURLToPath 可以在 ESM 配置文件中稳定地把相对 URL 转成绝对路径。

ts
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'

export default defineConfig({
  resolve: {
    alias: {
      // 运行时和构建阶段:@ 始终指向项目根目录下的 src
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
})

再把同一规则写入负责应用源码的 TypeScript 配置。Vite 官方模板常使用 tsconfig.app.json;若项目只有一个 tsconfig.json,就在该文件中配置。

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

@ 与 @/* 的写法职责不同:Vite 将导入前缀替换为绝对目录,TypeScript 则用通配符把 @/x 映射到 src/x。两边最终目录必须一致。

编写导入并执行验证

创建一个最小模块和入口引用。示例假设项目已有 src/main.ts,可以替换其中内容。

ts
// src/utils/format.ts
export function formatUser(name: string): string {
  return `User: ${name.trim()}`
}

// src/main.ts
import { formatUser } from '@/utils/format'

console.log(formatUser(' Ada '))

先让 TypeScript 检查编辑器侧配置,再让 Vite 执行生产构建。命令中的版本、模块数、文件大小和耗时会因项目而不同。

bash
npx tsc --noEmit && npm run build

预期输出

text
vite v<VERSION> building client environment for production...
✓ <COUNT> modules transformed.
dist/index.html                  <SIZE>
dist/assets/index-<ID>.js        <SIZE>
✓ built in <TIME>

tsc --noEmit 成功时通常没有输出;随后出现构建完成信息,说明 TypeScript 与 Vite 都能解析该别名。

处理典型不一致

编辑器仍报错时,先确认修改的是实际参与应用编译的 tsconfig,而不是只负责项目引用的根配置;随后重启编辑器的 TypeScript 服务。构建失败时,检查 replacement 是否为绝对路径、目录大小写是否与磁盘一致,以及导入是否错误写成 @utils/...。

不要让 Vite 指向 src、TypeScript 却指向 src/app。这类配置可能在部分文件中暂时可用,但重构、测试或 CI 构建时会暴露不一致。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置路径别名

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

登录哪都通