企业官网建设流程全解析

前阵子在部署一个 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 是严格按照“模块解析”逻辑来工作的。它会经过这些步骤：

1. 拿到 import 字符串。
2. 尝试与resolve.alias里的 key 做前缀匹配。
3. 如果匹配到，就替换成对应的绝对路径，然后继续解析。
4. 如果没有匹配，按相对路径、绝对路径、node_modules 顺序解析。
5. 解析不到就报错，并且把 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 语句的场景，比如动态 import：

const 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，我建议按下面五步来，基本能覆盖大部分情况：

1. 看报错里的 import 字符串，是相对路径、别名路径还是绝对路径。如果以/或@/开头，先去vite.config.ts里确认有没有匹配的 alias。
2. 看被引用的文件是否存在。注意大小写，Linux 构建环境下UserCard.vue和UserCard.vue不是一个文件，特别容易因为文件名大小写不匹配而报错。
3. 看路径是不是拼错了后缀。Vite 默认会解析.vue、.ts、.js、.jsx、.tsx等扩展名，但如果你在 import 里写了xxx.vue.ts这种奇怪后缀，大概率会失败。
4. 看配置文件是否生效。有时候项目里有多个vite.config.ts，比如根目录一个、src下一个，或者构建脚本指定了--config参数，但你只改了一个。
5. 看环境变量。import.meta.env相关的路径拼接如果在运行时才求出值，构建时往往无法确定，尽量用静态字符串。

5.2 静态资源 import 失败与 grenade.png 案例

还有一种常见报错是failed to resolve import "../assets/grenade (1024x128)[frames=8].png"。这种通常不是 alias 问题，而是文件名里有空格、括号、[frames=8]这类特殊字符。Vite 和 Rollup 对特殊字符的支持不算差，但有时会踩坑。

我的建议是，这类带特殊字符的图片资源直接重命名成简单格式，比如grenade-1024x128-frames8.png，然后重新引用。如果不想改文件名，可以加一层new URL方式：

import grenadeUrl from '/@/assets/grenade (1024x128)[frames=8].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 配置干净，构建日志自然就安静了。