前阵子在部署一个 Vue3 Vite 项目时npm run build刚跑起来就抛了一堆红字核心错误是Rollup failed to resolve import //api/user from src/views/system/user/index.vue。这个项目开发环境跑得一直好好的代码是import { getUserList } from //api/user这种写法结果一到了生产构建就翻车日志里还带着 Rollup、import、别名路径一系列关键词看起来很像 Vite 配置的问题又像是代码历史包袱。排查到凌晨最后发现根子不在配置多复杂而是import路径的别名写法跟vite.config里的alias对不上。如果你也遇到类似的 “dev 正常、build 报错” 的情况或者正在从老项目迁移到 Vite那这篇文章应该能帮你省掉不少时间。我会把整个排查过程、原理分析和最终落地的修复方案都写清楚最后再附一份我常用的避坑清单。1. 问题现场与初步定位1.1 报错信息长什么样当时的项目技术栈是 Vue 3.2 Vite 3 TypeScript Pinia部署目标是 Nginx。业务代码里大量保留了类似这样的导入写法import { getUserList } from //api/user import UserCard from //components/UserCard.vue执行npm run build后控制台出现一串类似下面的错误[email protected] build: vite build --mode test vite v3.2.5 building for production... transforming... [ERROR] Rollup failed to resolve import //api/user from src/views/system/user/index.vue. This is most likely unintended because it can break your application at runtime.接着还会跟着一堆error during build和文件路径整个构建过程直接中断。最让人疑惑的是同一个文件在开发环境npm run dev下访问完全正常接口也能通组件也能渲染所以一开始我根本没往代码路径写法上想先怀疑是不是构建命令、环境变量或者 Nginx 部署配置有问题。我当时的排查顺序是这样的先确认是不是--mode test导致的环境变量缺失反复检查.env.test、.env.production里的配置。再检查vite.config.ts里的resolve.alias确认了指向src目录没问题。然后看package.json的构建脚本确认没有多余的rollupOptions.external。最后回到报错本身把 import 字符串原封不动拿去搜索才发现项目里到处是//这种路径前缀而别名配置里根本没有对应项。其实很多人遇到这个问题时第一步就走偏了因为报错里的//api/user看起来像某种 URL 或网络路径潜意识会觉得是部署环境、代理或者 Nginx 的问题。实际上 Vite 构建过程不会去读网络资源它只会把这个字符串当作模块标识符交给 Rollup 解析一旦解析不到就直接放弃。1.2 开发环境和生产构建的解析差异为什么开发环境没问题这是很多人的第一反应。Vite 的 dev server 本身就是一个资源服务器它的模块解析逻辑和生产构建并不完全一致。开发模式下浏览器会向 dev server 请求每个模块import //api/user这个字符串会作为请求路径发到本地服务器。如果你的 Vite 配置里恰好有//相关的 alias或者项目里有某些中间件把它转到了src目录那浏览器拿到的是转换后的模块页面自然正常。即使没有 alias 匹配某些情况下 dev server 的server.fs.allow配置和根路径处理也可能让它“误打误撞”地找到文件这也是为什么很多问题只在 build 阶段暴露。生产构建就不一样了。vite build本质上是调用 Rollup 做打包Rollup 不启动服务器不做网络请求也不会像浏览器那样把//xxx当成 URL 来访问。它面对的是一个字符串需要通过配置的resolve.alias、扩展名解析规则、绝对路径规则去定位真实文件。如果 alias 没匹配或者匹配规则有问题就会直接报Rollup failed to resolve import。换句话说开发环境的成功掩盖了路径写法的隐患等到构建时才集中爆炸。这提醒我一个很重要的原则开发环境能跑不代表代码没问题commit 之前至少要跑一次vite build尤其是涉及大量 import 路径的项目。2. 根因别名配置、路径写法和构建链路2.1 别名配置与 import 路径要“门当户对”Vite 的别名配置核心是resolve.alias它是一个对象key 是你在代码里写的路径前缀value 是实际指向的目录。最常见的是import path from path import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], resolve: { alias: { : path.resolve(__dirname, src) } } })这段配置的意思是如果代码里写import xxx from /components/xxx构建时会把替换成项目根目录下的src最终解析到src/components/xxx。但问题代码写的是import xxx from //components/xxx注意开头多了一个/。很多人会想当然觉得和//差不多其实差远了。在 Vite 的 alias 匹配规则里不会匹配//因为匹配是按字符串前缀来的//api/user这个字符串的前缀是//而不是。除非你增加一个 key//否则它就是一个匹配不到任何 alias 的裸路径。更麻烦的是以/开头的字符串在解析时会被视为绝对路径Rollup 会尝试从文件系统根目录一层层往下找。比如//api/user会被理解为“文件系统根目录下的/api/user”这显然不存在。某些场景下 Vite 会对这种路径做特殊处理但构建阶段往往不会那么宽容。所以我建议把 alias 理解成“门禁系统”代码里写什么前缀配置里就要有对应的 key否则就进不了门。常见的组合是/对应path.resolve(__dirname, src)或者components/对应path.resolve(__dirname, src/components)。关键是 key 和实际 import 的第一个字符一定要严格匹配不能多一个/也不能少一个/。2.2 为什么 build 阶段 Rollup 会突然变严格Vite 开发服务其实做了很多容错处理比如当 import 路径解析不到时它可能仍然返回一个可以被浏览器接受的模块或者通过server.fs.allow放行某些路径。甚至在某些老版本的 Vite 模板里//被用作内部模块的约定前缀比如热更新相关的/vite/client、依赖预构建相关的/id/等这会让后来接手的人以为//是官方推荐的源码路径前缀于是大量使用。到了 build 阶段Rollup 是严格按照“模块解析”逻辑来工作的。它会经过这些步骤拿到 import 字符串。尝试与resolve.alias里的 key 做前缀匹配。如果匹配到就替换成对应的绝对路径然后继续解析。如果没有匹配按相对路径、绝对路径、node_modules 顺序解析。解析不到就报错并且把 resolve id 和引用它的文件一起打印出来。这个链路非常“死板”不会因为你开发环境能跑就自动放行。所以最终根因总结起来就是代码里使用了一个 alias 配置之外的前缀它借用了 Vite 开发环境的容错能力却在 Rollup 的严格解析下原形毕露。这类问题在从 Webpack 迁移到 Vite 的旧项目里尤其常见因为 Webpack 的resolve.alias同样要求 key 完全匹配但有些代码脚手架或项目模板早期用了不同的别名风格导致迁移时把两种写法混在一起。3. 解决方案实战从配置彻底修到代码收尾3.1 先修正 vite.config.ts 的 alias 配置临时修复最快的方式是把vite.config.ts里的 alias 同时兼容//前缀。我当时是这样改的import path from path import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], resolve: { alias: { : path.resolve(__dirname, src), //: path.resolve(__dirname, src) } } })注意 key 是//不是/。因为 import 字符串是//api/user前缀匹配需要覆盖//这三段字符替换后才得到path.resolve(__dirname, src) /api/user等于最终解析到src/api/user。为什么我说这是临时修复因为兼容写法会让项目里同时存在/api/user和//api/user两种风格。短期能解决 build 报错但长期来看代码风格不统一后续维护成本很高。而且如果哪天有人清理配置删掉了//这个 alias隐藏的问题会立刻复发。3.2 统一全局的//为/真正彻底的方案是把所有代码里的//替换成/和 alias 的保持统一。我当时用了两个工具VSCode 的全局搜索替换和命令行 sed。如果你在 VSCode 里操作可以打开搜索面板勾选正则表达式搜索from //然后全部替换为from /注意替换后的路径一定要保留后面的内容比如from //api/user变成from /api/user。在 VSCode 里使用带引号的搜索词时要注意单引号是否被正确处理稳妥一点的做法是搜索//然后手动检查预览再替换。命令行方式更直接适合文件数量特别多的项目grep -rl from // src | xargs sed -i s#from //#from /g这条命令会把src目录下所有from //写成from /。如果你的代码里还有不是 import 语句的场景比如动态 importconst Comp defineAsyncComponent(() import(//components/DeptTree.vue))或者 CSS 里的引入import //styles/variables.css;这些都要一起处理使用类似的替换规则grep -rl import(// src | xargs sed -i s#import(//#import(/#g grep -rl import // src | xargs sed -i s#import //#import /g替换完成后强烈建议用 grep 再扫一遍确认没有残留grep -rn // src理想情况下应该没有任何输出。有输出就说明还有漏网之鱼继续逐一处理。3.3 配套 tsconfig 与类型提示代码路径统一成/后还需要保证 TypeScript 和 VSCode 能识别这个路径别名否则编辑器会飘红虽然 build 可能能过但开发体验很差。在tsconfig.json中加上{ compilerOptions: { baseUrl: ., paths: { /*: [src/*] } } }baseUrl是基础路径paths里的键/*表示/xxx这种写法值[src/*]表示映射到src/xxx。这样 TypeScript 的类型检查、自动补全、点击跳转都能正常工作。如果你是 Vue 3 Vite 项目tsconfig可能会有两个一个是tsconfig.app.json一个是tsconfig.node.json需要在业务代码所在的那个文件里配置paths。有时候改完tsconfig后编辑器不会立即生效重启一下 VSCode 或者运行一次Vite: Reload Project就好。最后重新执行npm run build这次构建过程应该顺畅不少。如果还有类似的Rollup failed to resolve import报错继续按报错提示的文件路径和 import 字符串排查一般还是别名或路径写法的锅方法和上面一样。4. 部署场景中容易一起踩的四个坑4.1 base 配置不对导致静态资源 404构建成功不代表部署没问题。如果你的项目不是部署在域名根路径下而是放在某个子目录比如https://example.com/admin/下就必须设置 Vite 的base配置export default defineConfig({ base: /admin/ })如果你设置的是相对路径base: ./在部分路由场景下资源路径会变成相对当前路由容易造成嵌套路由刷新后 JS/CSS 404。alias 本身和base没有直接关系但很多人把路径别名和资源路径混在一起排查时会走弯路。我之前就遇到过构建通过页面打开空白控制台报Failed to load module script原因是assets资源路径前缀不对。解决办法就是根据部署位置统一base并确保 Nginx 的try_files配置能正确回退到index.html。4.2 build.rollupOptions.external 误伤还有一种情况是构建配置里手动写了rollupOptions.external把某些本来应该打包的路径标记成了外部依赖。比如build: { rollupOptions: { external: [//api/user] } }这样写会导致 Rollup 不再去解析//api/user但实际部署时浏览器根本拿不到这个“外部模块”运行时就会白屏或报Failed to fetch dynamically imported module。这类配置通常是从某个代码片段里抄来的或者为了处理某些第三方库的 external 需求时顺手加上了。排查方法很简单把external里的值和报错里的 import 字符串比对一下如果是业务代码路径直接删掉。4.3 动态 import 拼接路径有些项目会把路径写成动态拼接比如const filePath // name /index.vue const Comp defineAsyncComponent(() import(filePath))这种写法在 Vite 下非常危险。Rollup 的静态分析能力有限对于完全动态的变量路径它通常无法在构建时确定到底要打包哪些模块会导致解析失败或者把所有可能文件都打进去。正确做法是使用相对路径并且尽量让路径可被静态分析const Comp defineAsyncComponent(() import(../components/${name}/index.vue))Vite 对这种模板字符串路径有一定的分析能力但目录范围太大时也可能失控。如果必须用别名建议写成import(/components/ name /index.vue)同时确保是配置过的 alias并且目录层级简单。4.4 monorepo 与依赖预构建如果你的项目在 monorepo 里源码引用了workspace下的另一个包而这个包内部又用了//或/这样的路径别名情况会更复杂。Vite 在构建时会尝试解析这些包的真实文件如果别名没有传递到子包同样会报Rollup failed to resolve import。处理思路有三种一是子包内尽量用相对路径发布 npm 包时不要依赖宿主项目的 alias二是在 Vite 配置中继续增加 alias指向子包内部的src目录三是用optimizeDeps.exclude把不需要预构建的包排除掉。但最稳妥的还是相对路径因为 alias 本质上是工程化约定不应该成为独立模块之间的强依赖。5. 同类报错快速排查清单5.1 通用排查五步以后再遇到 Vite 构建时Rollup failed to resolve import我建议按下面五步来基本能覆盖大部分情况看报错里的 import 字符串是相对路径、别名路径还是绝对路径。如果以/或/开头先去vite.config.ts里确认有没有匹配的 alias。看被引用的文件是否存在。注意大小写Linux 构建环境下UserCard.vue和UserCard.vue不是一个文件特别容易因为文件名大小写不匹配而报错。看路径是不是拼错了后缀。Vite 默认会解析.vue、.ts、.js、.jsx、.tsx等扩展名但如果你在 import 里写了xxx.vue.ts这种奇怪后缀大概率会失败。看配置文件是否生效。有时候项目里有多个vite.config.ts比如根目录一个、src下一个或者构建脚本指定了--config参数但你只改了一个。看环境变量。import.meta.env相关的路径拼接如果在运行时才求出值构建时往往无法确定尽量用静态字符串。5.2 静态资源 import 失败与 grenade.png 案例还有一种常见报错是failed to resolve import ../assets/grenade (1024x128)[frames8].png。这种通常不是 alias 问题而是文件名里有空格、括号、[frames8]这类特殊字符。Vite 和 Rollup 对特殊字符的支持不算差但有时会踩坑。我的建议是这类带特殊字符的图片资源直接重命名成简单格式比如grenade-1024x128-frames8.png然后重新引用。如果不想改文件名可以加一层new URL方式import grenadeUrl from //assets/grenade (1024x128)[frames8].png前提是//对应正确的 alias。更推荐的是直接把文件放到public目录然后用import.meta.env.BASE_URL images/grenade.png来引用这样最省心因为public目录下的文件不会经过构建解析但也不会被打包过程影响。5.3 我常用的两个避坑脚本为了减少这类问题的复发我在项目里加了两个小脚本放在scripts/check-alias.mjs里。第一个是检查代码里是否出现无法匹配的//路径import { readdirSync, statSync, readFileSync } from node:fs import { join } from node:path const dir join(process.cwd(), src) const files [] function walk(p) { for (const name of readdirSync(p)) { const full join(p, name) if (statSync(full).isDirectory()) walk(full) else if (/\.(vue|ts|tsx|js|jsx|css|scss)$/.test(full)) files.push(full) } } walk(dir) for (const file of files) { const content readFileSync(file, utf8) if (content.includes(from //) || content.includes(import(//)) { console.error(Found // in, file) process.exit(1) } } console.log(Alias path check passed.)第二个是校验vite.config.ts里的 alias key 是否覆盖了代码中实际使用的前缀原理简单这里就不贴完整代码了。重点是把它挂到prebuild脚本里{ scripts: { prebuild: node scripts/check-alias.mjs, build: vite build } }这样每次npm run build之前都会自动扫描一遍把问题挡在构建开始之前省得每次都在一堆报错日志里翻。6. 一点个人体会这次问题解决之后我给团队立了一条规矩所有源码内的模块导入要么用相对路径要么用/开头的前缀禁止以/开头自定义目录。因为以/开头的路径在开发环境里很容易被 Vite 的 HTTP 服务器“惯坏”看起来一切正常但到了打包环节就是定时炸弹。如果你现在正被类似的报错折磨建议不要急着改rollupOptions先冷静下来把 import 字符串和 alias 配置对比一遍。很多时候问题并没有想象中复杂只是 dev 模式的便利掩盖了构建链路的严格性。把路径统一好把 alias 配置干净构建日志自然就安静了。
前阵子在部署一个 Vue3 Vite 项目时npm run build刚跑起来就抛了一堆红字核心错误是Rollup failed to resolve import //api/user from src/views/system/user/index.vue。这个项目开发环境跑得一直好好的代码是import { getUserList } from //api/user这种写法结果一到了生产构建就翻车日志里还带着 Rollup、import、别名路径一系列关键词看起来很像 Vite 配置的问题又像是代码历史包袱。排查到凌晨最后发现根子不在配置多复杂而是import路径的别名写法跟vite.config里的alias对不上。如果你也遇到类似的 “dev 正常、build 报错” 的情况或者正在从老项目迁移到 Vite那这篇文章应该能帮你省掉不少时间。我会把整个排查过程、原理分析和最终落地的修复方案都写清楚最后再附一份我常用的避坑清单。1. 问题现场与初步定位1.1 报错信息长什么样当时的项目技术栈是 Vue 3.2 Vite 3 TypeScript Pinia部署目标是 Nginx。业务代码里大量保留了类似这样的导入写法import { getUserList } from //api/user import UserCard from //components/UserCard.vue执行npm run build后控制台出现一串类似下面的错误[email protected] build: vite build --mode test vite v3.2.5 building for production... transforming... [ERROR] Rollup failed to resolve import //api/user from src/views/system/user/index.vue. This is most likely unintended because it can break your application at runtime.接着还会跟着一堆error during build和文件路径整个构建过程直接中断。最让人疑惑的是同一个文件在开发环境npm run dev下访问完全正常接口也能通组件也能渲染所以一开始我根本没往代码路径写法上想先怀疑是不是构建命令、环境变量或者 Nginx 部署配置有问题。我当时的排查顺序是这样的先确认是不是--mode test导致的环境变量缺失反复检查.env.test、.env.production里的配置。再检查vite.config.ts里的resolve.alias确认了指向src目录没问题。然后看package.json的构建脚本确认没有多余的rollupOptions.external。最后回到报错本身把 import 字符串原封不动拿去搜索才发现项目里到处是//这种路径前缀而别名配置里根本没有对应项。其实很多人遇到这个问题时第一步就走偏了因为报错里的//api/user看起来像某种 URL 或网络路径潜意识会觉得是部署环境、代理或者 Nginx 的问题。实际上 Vite 构建过程不会去读网络资源它只会把这个字符串当作模块标识符交给 Rollup 解析一旦解析不到就直接放弃。1.2 开发环境和生产构建的解析差异为什么开发环境没问题这是很多人的第一反应。Vite 的 dev server 本身就是一个资源服务器它的模块解析逻辑和生产构建并不完全一致。开发模式下浏览器会向 dev server 请求每个模块import //api/user这个字符串会作为请求路径发到本地服务器。如果你的 Vite 配置里恰好有//相关的 alias或者项目里有某些中间件把它转到了src目录那浏览器拿到的是转换后的模块页面自然正常。即使没有 alias 匹配某些情况下 dev server 的server.fs.allow配置和根路径处理也可能让它“误打误撞”地找到文件这也是为什么很多问题只在 build 阶段暴露。生产构建就不一样了。vite build本质上是调用 Rollup 做打包Rollup 不启动服务器不做网络请求也不会像浏览器那样把//xxx当成 URL 来访问。它面对的是一个字符串需要通过配置的resolve.alias、扩展名解析规则、绝对路径规则去定位真实文件。如果 alias 没匹配或者匹配规则有问题就会直接报Rollup failed to resolve import。换句话说开发环境的成功掩盖了路径写法的隐患等到构建时才集中爆炸。这提醒我一个很重要的原则开发环境能跑不代表代码没问题commit 之前至少要跑一次vite build尤其是涉及大量 import 路径的项目。2. 根因别名配置、路径写法和构建链路2.1 别名配置与 import 路径要“门当户对”Vite 的别名配置核心是resolve.alias它是一个对象key 是你在代码里写的路径前缀value 是实际指向的目录。最常见的是import path from path import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], resolve: { alias: { : path.resolve(__dirname, src) } } })这段配置的意思是如果代码里写import xxx from /components/xxx构建时会把替换成项目根目录下的src最终解析到src/components/xxx。但问题代码写的是import xxx from //components/xxx注意开头多了一个/。很多人会想当然觉得和//差不多其实差远了。在 Vite 的 alias 匹配规则里不会匹配//因为匹配是按字符串前缀来的//api/user这个字符串的前缀是//而不是。除非你增加一个 key//否则它就是一个匹配不到任何 alias 的裸路径。更麻烦的是以/开头的字符串在解析时会被视为绝对路径Rollup 会尝试从文件系统根目录一层层往下找。比如//api/user会被理解为“文件系统根目录下的/api/user”这显然不存在。某些场景下 Vite 会对这种路径做特殊处理但构建阶段往往不会那么宽容。所以我建议把 alias 理解成“门禁系统”代码里写什么前缀配置里就要有对应的 key否则就进不了门。常见的组合是/对应path.resolve(__dirname, src)或者components/对应path.resolve(__dirname, src/components)。关键是 key 和实际 import 的第一个字符一定要严格匹配不能多一个/也不能少一个/。2.2 为什么 build 阶段 Rollup 会突然变严格Vite 开发服务其实做了很多容错处理比如当 import 路径解析不到时它可能仍然返回一个可以被浏览器接受的模块或者通过server.fs.allow放行某些路径。甚至在某些老版本的 Vite 模板里//被用作内部模块的约定前缀比如热更新相关的/vite/client、依赖预构建相关的/id/等这会让后来接手的人以为//是官方推荐的源码路径前缀于是大量使用。到了 build 阶段Rollup 是严格按照“模块解析”逻辑来工作的。它会经过这些步骤拿到 import 字符串。尝试与resolve.alias里的 key 做前缀匹配。如果匹配到就替换成对应的绝对路径然后继续解析。如果没有匹配按相对路径、绝对路径、node_modules 顺序解析。解析不到就报错并且把 resolve id 和引用它的文件一起打印出来。这个链路非常“死板”不会因为你开发环境能跑就自动放行。所以最终根因总结起来就是代码里使用了一个 alias 配置之外的前缀它借用了 Vite 开发环境的容错能力却在 Rollup 的严格解析下原形毕露。这类问题在从 Webpack 迁移到 Vite 的旧项目里尤其常见因为 Webpack 的resolve.alias同样要求 key 完全匹配但有些代码脚手架或项目模板早期用了不同的别名风格导致迁移时把两种写法混在一起。3. 解决方案实战从配置彻底修到代码收尾3.1 先修正 vite.config.ts 的 alias 配置临时修复最快的方式是把vite.config.ts里的 alias 同时兼容//前缀。我当时是这样改的import path from path import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], resolve: { alias: { : path.resolve(__dirname, src), //: path.resolve(__dirname, src) } } })注意 key 是//不是/。因为 import 字符串是//api/user前缀匹配需要覆盖//这三段字符替换后才得到path.resolve(__dirname, src) /api/user等于最终解析到src/api/user。为什么我说这是临时修复因为兼容写法会让项目里同时存在/api/user和//api/user两种风格。短期能解决 build 报错但长期来看代码风格不统一后续维护成本很高。而且如果哪天有人清理配置删掉了//这个 alias隐藏的问题会立刻复发。3.2 统一全局的//为/真正彻底的方案是把所有代码里的//替换成/和 alias 的保持统一。我当时用了两个工具VSCode 的全局搜索替换和命令行 sed。如果你在 VSCode 里操作可以打开搜索面板勾选正则表达式搜索from //然后全部替换为from /注意替换后的路径一定要保留后面的内容比如from //api/user变成from /api/user。在 VSCode 里使用带引号的搜索词时要注意单引号是否被正确处理稳妥一点的做法是搜索//然后手动检查预览再替换。命令行方式更直接适合文件数量特别多的项目grep -rl from // src | xargs sed -i s#from //#from /g这条命令会把src目录下所有from //写成from /。如果你的代码里还有不是 import 语句的场景比如动态 importconst Comp defineAsyncComponent(() import(//components/DeptTree.vue))或者 CSS 里的引入import //styles/variables.css;这些都要一起处理使用类似的替换规则grep -rl import(// src | xargs sed -i s#import(//#import(/#g grep -rl import // src | xargs sed -i s#import //#import /g替换完成后强烈建议用 grep 再扫一遍确认没有残留grep -rn // src理想情况下应该没有任何输出。有输出就说明还有漏网之鱼继续逐一处理。3.3 配套 tsconfig 与类型提示代码路径统一成/后还需要保证 TypeScript 和 VSCode 能识别这个路径别名否则编辑器会飘红虽然 build 可能能过但开发体验很差。在tsconfig.json中加上{ compilerOptions: { baseUrl: ., paths: { /*: [src/*] } } }baseUrl是基础路径paths里的键/*表示/xxx这种写法值[src/*]表示映射到src/xxx。这样 TypeScript 的类型检查、自动补全、点击跳转都能正常工作。如果你是 Vue 3 Vite 项目tsconfig可能会有两个一个是tsconfig.app.json一个是tsconfig.node.json需要在业务代码所在的那个文件里配置paths。有时候改完tsconfig后编辑器不会立即生效重启一下 VSCode 或者运行一次Vite: Reload Project就好。最后重新执行npm run build这次构建过程应该顺畅不少。如果还有类似的Rollup failed to resolve import报错继续按报错提示的文件路径和 import 字符串排查一般还是别名或路径写法的锅方法和上面一样。4. 部署场景中容易一起踩的四个坑4.1 base 配置不对导致静态资源 404构建成功不代表部署没问题。如果你的项目不是部署在域名根路径下而是放在某个子目录比如https://example.com/admin/下就必须设置 Vite 的base配置export default defineConfig({ base: /admin/ })如果你设置的是相对路径base: ./在部分路由场景下资源路径会变成相对当前路由容易造成嵌套路由刷新后 JS/CSS 404。alias 本身和base没有直接关系但很多人把路径别名和资源路径混在一起排查时会走弯路。我之前就遇到过构建通过页面打开空白控制台报Failed to load module script原因是assets资源路径前缀不对。解决办法就是根据部署位置统一base并确保 Nginx 的try_files配置能正确回退到index.html。4.2 build.rollupOptions.external 误伤还有一种情况是构建配置里手动写了rollupOptions.external把某些本来应该打包的路径标记成了外部依赖。比如build: { rollupOptions: { external: [//api/user] } }这样写会导致 Rollup 不再去解析//api/user但实际部署时浏览器根本拿不到这个“外部模块”运行时就会白屏或报Failed to fetch dynamically imported module。这类配置通常是从某个代码片段里抄来的或者为了处理某些第三方库的 external 需求时顺手加上了。排查方法很简单把external里的值和报错里的 import 字符串比对一下如果是业务代码路径直接删掉。4.3 动态 import 拼接路径有些项目会把路径写成动态拼接比如const filePath // name /index.vue const Comp defineAsyncComponent(() import(filePath))这种写法在 Vite 下非常危险。Rollup 的静态分析能力有限对于完全动态的变量路径它通常无法在构建时确定到底要打包哪些模块会导致解析失败或者把所有可能文件都打进去。正确做法是使用相对路径并且尽量让路径可被静态分析const Comp defineAsyncComponent(() import(../components/${name}/index.vue))Vite 对这种模板字符串路径有一定的分析能力但目录范围太大时也可能失控。如果必须用别名建议写成import(/components/ name /index.vue)同时确保是配置过的 alias并且目录层级简单。4.4 monorepo 与依赖预构建如果你的项目在 monorepo 里源码引用了workspace下的另一个包而这个包内部又用了//或/这样的路径别名情况会更复杂。Vite 在构建时会尝试解析这些包的真实文件如果别名没有传递到子包同样会报Rollup failed to resolve import。处理思路有三种一是子包内尽量用相对路径发布 npm 包时不要依赖宿主项目的 alias二是在 Vite 配置中继续增加 alias指向子包内部的src目录三是用optimizeDeps.exclude把不需要预构建的包排除掉。但最稳妥的还是相对路径因为 alias 本质上是工程化约定不应该成为独立模块之间的强依赖。5. 同类报错快速排查清单5.1 通用排查五步以后再遇到 Vite 构建时Rollup failed to resolve import我建议按下面五步来基本能覆盖大部分情况看报错里的 import 字符串是相对路径、别名路径还是绝对路径。如果以/或/开头先去vite.config.ts里确认有没有匹配的 alias。看被引用的文件是否存在。注意大小写Linux 构建环境下UserCard.vue和UserCard.vue不是一个文件特别容易因为文件名大小写不匹配而报错。看路径是不是拼错了后缀。Vite 默认会解析.vue、.ts、.js、.jsx、.tsx等扩展名但如果你在 import 里写了xxx.vue.ts这种奇怪后缀大概率会失败。看配置文件是否生效。有时候项目里有多个vite.config.ts比如根目录一个、src下一个或者构建脚本指定了--config参数但你只改了一个。看环境变量。import.meta.env相关的路径拼接如果在运行时才求出值构建时往往无法确定尽量用静态字符串。5.2 静态资源 import 失败与 grenade.png 案例还有一种常见报错是failed to resolve import ../assets/grenade (1024x128)[frames8].png。这种通常不是 alias 问题而是文件名里有空格、括号、[frames8]这类特殊字符。Vite 和 Rollup 对特殊字符的支持不算差但有时会踩坑。我的建议是这类带特殊字符的图片资源直接重命名成简单格式比如grenade-1024x128-frames8.png然后重新引用。如果不想改文件名可以加一层new URL方式import grenadeUrl from //assets/grenade (1024x128)[frames8].png前提是//对应正确的 alias。更推荐的是直接把文件放到public目录然后用import.meta.env.BASE_URL images/grenade.png来引用这样最省心因为public目录下的文件不会经过构建解析但也不会被打包过程影响。5.3 我常用的两个避坑脚本为了减少这类问题的复发我在项目里加了两个小脚本放在scripts/check-alias.mjs里。第一个是检查代码里是否出现无法匹配的//路径import { readdirSync, statSync, readFileSync } from node:fs import { join } from node:path const dir join(process.cwd(), src) const files [] function walk(p) { for (const name of readdirSync(p)) { const full join(p, name) if (statSync(full).isDirectory()) walk(full) else if (/\.(vue|ts|tsx|js|jsx|css|scss)$/.test(full)) files.push(full) } } walk(dir) for (const file of files) { const content readFileSync(file, utf8) if (content.includes(from //) || content.includes(import(//)) { console.error(Found // in, file) process.exit(1) } } console.log(Alias path check passed.)第二个是校验vite.config.ts里的 alias key 是否覆盖了代码中实际使用的前缀原理简单这里就不贴完整代码了。重点是把它挂到prebuild脚本里{ scripts: { prebuild: node scripts/check-alias.mjs, build: vite build } }这样每次npm run build之前都会自动扫描一遍把问题挡在构建开始之前省得每次都在一堆报错日志里翻。6. 一点个人体会这次问题解决之后我给团队立了一条规矩所有源码内的模块导入要么用相对路径要么用/开头的前缀禁止以/开头自定义目录。因为以/开头的路径在开发环境里很容易被 Vite 的 HTTP 服务器“惯坏”看起来一切正常但到了打包环节就是定时炸弹。如果你现在正被类似的报错折磨建议不要急着改rollupOptions先冷静下来把 import 字符串和 alias 配置对比一遍。很多时候问题并没有想象中复杂只是 dev 模式的便利掩盖了构建链路的严格性。把路径统一好把 alias 配置干净构建日志自然就安静了。
