[!info] related notes

• 所属：Vite 基础 MOC
• 相关：TS paths · 环境变量

Vite 配置与路径别名

这个概念为什么出现

@/components/Button 提升可读性，但只配 Vite 不配 TS 会出现“能跑编辑器红线”，或“类型过了构建挂”。

[!abstract] 一句话理解 Vite alias 管运行/构建解析；tsconfig paths 管类型与 IDE；两者是同一契约的两边。

最小示例

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

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
  server: { port: 5173 },
  build: { sourcemap: true },
})

同时在实际包含应用源码的 tsconfig（如 tsconfig.app.json）配置；仅写入带 references 的根 tsconfig，不会自动传给子项目：

{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

Vite 8 也支持显式开启 resolve.tsconfigPaths: true 读取 tsconfig 路径映射；默认关闭。采用这种方式时可以减少重复 alias 配置，但仍需确认实际应用 tsconfig 生效，并同时验证类型检查和构建。

配置分段直觉

• plugins：转换能力
• resolve：解析
• server：开发服务器；部分配置被 preview 默认继承，如 proxy
• build：仅产物
• define：常量替换；环境文件目录与客户端前缀由 envDir / envPrefix 控制，没有通用顶层 env 配置段

本节总结

别名是跨工具合同；改一处要改一组。

自测题

1. 为什么 alias 用绝对路径更稳？

参考答案

Vite 的 alias replacement 若为相对路径，会按原值使用，不自动解析为绝对文件路径。示例用 import.meta.url 锚定配置文件，不依赖工作目录或 ESM 中不存在的 __dirname。