Vue 3 + TypeScript项目@路径别名仅TS文件生效、模板内失效

问题核心根因 #

该场景的本质是两类路径解析逻辑的作用域完全隔离，未完成规则打通：

• 负责TS脚本、模块导入的路径解析：覆盖所有.ts文件、SFC文件<script>块内的导入语句，依赖构建工具配置的模块解析规则、以及tsconfig.json中配置的paths规则完成类型校验与构建映射。这部分配置正确时，所有脚本内的@路径都能正常解析，与观察到的“script块导入正常”的现象完全匹配。
• 负责SFC模板静态属性的资源解析：专门处理模板中src、href等被识别为静态资源引用的属性值，这套逻辑由Vue模板编译器内置的资源URL转换模块独立运行，不会自动读取tsconfig.json的paths配置，也不会默认继承构建工具的模块别名规则。如果没有主动给这套逻辑同步@别名的映射关系，编译器就会把@/assets/logo.png当成普通字符串直接输出到最终DOM上，不做路径重写，自然会出现图片加载失败的问题。

复现分支与正常分支的关键差异 #

两个分支的核心区别集中在「是否打通模板资源解析逻辑的别名规则」，常见的配置差异包括：

• 构建工具配置层面：
  • 复现分支仅在tsconfig.json中配置了@/*的paths映射、设置了根目录的baseUrl，没有在构建工具的配置文件（如vue.config.js、vite.config.ts）中显式注册@的路径别名；
  • 正常分支会在构建工具配置中明确声明@对应src目录的映射规则：Webpack项目通过configureWebpack.resolve.alias配置别名，Vite项目通过resolve.alias配置相同映射，让模板编译阶段的资源转换逻辑能正确识别@的指向。
• 模板写法层面：
  • 复现分支直接在模板的静态属性上硬编码src="@/assets/logo.png"，完全依赖编译器的自动路径转换能力；
  • 部分正常分支会采用动态绑定的方式引用资源：在script块中通过import logoUrl from '@/assets/logo.png'导入图片资源，再在模板中通过<img :src="logoUrl">绑定，这套写法走的是正常的模块导入逻辑，不依赖模板静态资源转换的别名解析，因此也能正常运行。
• 依赖版本层面：
  • 部分复现仓库存在依赖版本错位问题：比如使用了不支持自动读取tsconfig paths做模板资源解析的旧版@vue/compiler-sfc，导致模板编译阶段无法获取到别名映射规则；正常分支会将编译器相关依赖升级到与Vue 3核心版本匹配的稳定版本，打通两类解析逻辑的规则读取通道。

内容的提问来源于stack exchange，提问作者Natalie Perret