企业官网建设流程全解析

Vue 项目里写静态资源路径，看着简单，实际坑不少。前两天帮同事排查一个线上问题，本地开发一切正常，打包部署后页面图片全挂，最后定位到根因就是路径写法和构建配置不匹配，导致编译后的资源 URL 指向了错误位置。这类问题在 Vue 开发者里太常见了，而且多半出在 相对路径、绝对路径、@ 别名、~ 前缀 这几种写法的底层逻辑没捋清楚。

这篇笔记我专门以图片引入为例，把这几种路径方式从头到尾梳理一遍：它们分别在什么场景下生效，编译后到底变成了什么，本地和打包部署有什么差异，以及最常见的几类报错怎么排查。另外我会给一个可以在线运行的演示工程，直接打开浏览器就能对照验证，不用先搭一堆环境。

1. 先理解底层：静态资源的两种存放姿势

1.1 src/assets 和 public 的本质区别

Vue 项目里放图片、字体、PDF 这类静态文件，常规位置就两个：src/assets和public。很多人只知道"一个会被打包一个不会"，但没理解背后的设计意图，导致后面选路径时全凭感觉。

先说src/assets。这个目录下的文件会经过完整构建处理，以 Vue CLI（Webpack）项目为例，图片资源统一交给url-loader/file-loader处理，小于设定阈值（默认约 4KB）的图片会直接转成 base64 字符串内联到 JS 里，这样能减少一次 HTTP 请求；超过阈值的则会被复制到打包输出目录，文件名自动加上 hash 指纹，类似logo.5c0b3a2f.png。指纹的作用是方便浏览器缓存更新——文件内容变了，文件名就变，不会命中旧缓存。

再看public目录。这个目录下的文件完全原样拷贝到dist根目录，不压缩、不指纹、不转 base64。访问方式也很直接：开发时public/logo.png对应 URL 路径/logo.png，打包后同样以/logo.png存在于服务器上。

选择标准其实很清晰：需要被构建处理、想吃压缩和指纹红利、由代码直接引用的资源，放src/assets；希望保持路径不变、不经过构建加工的资源，放public。比如 favicon、第三方合作方要固定访问的静态文件，就适合 public。但绝大多数业务图片，正确选择都是src/assets。

1.2 理解“编译时路径处理”是排坑的前提

排查路径问题最大的阻碍，是不少人默认浏览器会自己去解析这些路径。实际上 Vue 项目里的资源引用，绝大多数在"编译期"就被处理了：Webpack 或 Vite 在打包时，根据你代码里写的路径去解析真实文件，决定这个资源是转成 base64、输出成新文件，还是原样保留，然后把最终结果替换进编译产物。

我给你举个例子。模板里写<img src="./assets/logo.png">，浏览器并不是自己跑到服务器上去找./assets/logo.png这个相对路径，而是vue-loader在编译阶段先把这个文件解析出来，转成 base64 或生成带 hash 的新文件，最后把编译后的地址写进渲染函数。

理解了这一点，你就能解释很多诡异现象。比如 js 里动态拼接路径不生效，因为编译期根本不知道你运行时把字符串拼成了什么；比如@在 style 里偶尔失效，因为 CSS 的解析链路和 JS 不是一回事。所有路径坑，本质上都是"没分清这段路径是给编译器看的，还是给浏览器看的"。

2. 四种路径写法逐一拆解

2.1 相对路径（./ 和 ../）：最直观但最容易写乱

相对路径是以"当前文件所在目录"为基准去定位另一个文件。在 Vue 组件里，<img src="./assets/logo.png">表示去当前组件文件同级的assets目录找logo.png。

在template的img标签、style的url()中，相对路径都会被构建工具解析和加工，资源正常进入打包流程。所以从功能上，相对路径是能用的，而且在小项目里很直观，不用担心别名配置问题。

但它有个致命弱点：目录层级一深，../../../../../assets/logo.png这种写法会让代码丑到没法看，而且一旦调整目录结构，所有引用全部失效。你想想，一个组件如果你深挖到src/views/admin/user/components/ButtonGroup/index.vue，要引用根目录附近的图片，那../的数量数到怀疑人生。

我的建议是，相对路径只适合"引用和自己强相关的、距离很近的资源"，比如当前组件目录下的一个小图。其他情况尽量别用。

2.2 绝对路径（/ 开头）：与 public 目录深度绑定

这里说的"绝对路径"不是带域名的那种完整 URL，而是站内根路径写法，即/开头，比如/images/logo.png。它的解析规则非常简单：开发时去public目录里找对应文件，打包后原样输出到服务器根路径。

所以如果你写<img src="/images/logo.png">，团队里必须约定：public/images/logo.png这个文件确实存在。它不会经过 Webpack 或 Vite 处理，不会转 base64，也不会加 hash。

这种写法的坑主要在部署阶段。假如你的应用部署在https://example.com/myapp/这个子路径下，而代码里写的是/images/logo.png，浏览器会把它解析成https://example.com/images/logo.png——请求直接跑到域名根路径去了，自然 404。要解决这个问题，要么配合publicPath或base配置统一处理，要么干脆少用这种绝对路径。

2.3 @ 别名：指向 src 的灵魂写法

@本质上是一个路径别名（alias），它在构建配置里被指向src目录。你写@/assets/logo.png，编译器会把它当作src/assets/logo.png来解析。

Vue CLI 创建的项目默认配好了@，vue.config.js里也能看到相关配置。Vite 项目如果用的是 create-vue 新模板，@也默认可用；老项目或手动搭建的 Vite 项目，则需要自己在vite.config.js里配置：

// vite.config.js import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' import { fileURLToPath, URL } from 'node:url' export default defineConfig({ plugins: [vue()], resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } } })

@的好处就是终结../../灾难，代码可读性直线上升。它最常用于template和script中，基本畅通无阻。但在 Webpack 项目的style里直接写url('@/assets/logo.png')是有可能出问题的，因为css-loader对路径的解析和 JS 模块解析不是同一套逻辑，这时候就需要请出~前缀。

2.4 ~ 符号：主要服务于 CSS，别在 JS 里乱用

~这个符号对新手最不友好，因为它只在特定场景下有用。它的核心作用是：告诉 CSS 的解析器，后面这段内容不是普通路径，而是"模块路径"，请你把它交给 Webpack 按模块规则去解析。

典型场景有两个。第一个是~@/assets/logo.png，用来在 CSS 的url()里配合别名使用，解决上一节说的"style 里 @ 可能失效"的问题。第二个是引用node_modules里的资源，比如url('~bootstrap/dist/img/logo.png')，表示去node_modules下找bootstrap包里的文件。

需要特别注意的是，在 JS 和 template 里不需要也不应该加~。import logo from '~@/assets/logo.png'这种写法纯属多余，直接写@就行。

Vite 场景下~的存在感会弱不少，因为 Vite 对 CSS 中的别名解析支持得更好，你写@/assets/logo.png通常就能正常工作。不过为了兼容某些插件或历史项目，Vite 对~开头的内容也会特殊处理，剥掉~后当模块路径解析。所以~@在 Vite 里写了也不会报错，但我个人建议 Vite 项目里按官方文档走，少用~。

2.5 一张表总结四种写法

3. 三个高频场景实操

3.1 template 里的 img：静态与动态的区别

模板里引用图片，最常用的写法就是三种：相对路径、@别名、绝对路径。

<!-- 相对路径，编译期解析，资源会被构建处理 --> <img src="./assets/logo.png" alt="logo" /> <!-- @ 别名，推荐写法 --> <img src="@/assets/logo.png" alt="logo" /> <!-- 绝对路径，对应 public/images/logo.png，不构建处理 --> <img src="/images/logo.png" alt="logo" />

关键区别在动态绑定。如果你写成:src="imgUrl"，并且imgUrl是通过字符串拼接出来的，比如'@/assets/' + name + '.png'，那这张图必然出不来。原因在前面讲过：编译器在打包时面对的是一个动态字符串，它没法静态分析出真实文件是谁，于是只能原样输出，而浏览器拿到@/assets/xxx.png这种地址根本不知道去哪找。

正确的动态引入姿势是这样的：

<script setup> import logo from '@/assets/logo.png' </script> <template> <img :src="logo" alt="logo" /> </template>

先把图片 import 进来作为一个模块对象，再绑定给src，让编译器在 import 阶段就知道资源位置。后面我会在在线演示里跑这个场景。

3.2 style 里的 background：别踩别名失效的坑

CSS 里引用背景图，写法上比模板更讲究。

<style scoped> .box { /* Webpack 项目：推荐 ~@ 写法 */ background: url('~@/assets/bg.png') center center / cover no-repeat; } </style>

为什么这里要用~@而不是直接@？因为 CSS 文件在被css-loader解析时，url()里的路径默认会被当作相对路径处理。直接写@/assets/bg.png，css-loader不知道@是什么，可能直接报错，或者把它解析成一个错误的相对路径。加了~前缀之后，css-loader就会明白"这是模块路径"，转交给 Webpack 的模块解析逻辑，@别名也就能正确生效了。

Vite 项目就没这么折腾，CSS 里直接写@/assets/bg.png就能被正确解析。不过如果你是从老项目迁移过来的，遇到<style>里@失效，先检查 Vite 的resolve.alias是否配置，再看当前版本对 CSS 别名支持是否有异常。

还有一点，scoped属性只影响样式作用域，不影响资源路径解析，别在这上面绕弯。

3.3 script 里引入图片：import、require 与 new URL

现在写 Vue 3 + Vite 是主流，我先说这种组合下的推荐做法。在<script setup>里引入图片，通常有两种方式：

// 方式一：静态 import，编译器能解析，Vite/Webpack 都支持 import logo from '@/assets/logo.png' // 方式二：运行时动态路径，Vite 推荐用 new URL function getLogo(name) { return new URL(`../assets/${name}.png`, import.meta.url).href }

new URL(..., import.meta.url)是 Vite 官方推荐的动态资源引用方式，它让浏览器在运行时基于import.meta.url（当前模块的 URL）去解析相对路径，这样就不需要预先知道所有文件名。

如果你还在用 Vue CLI 或者老版本 Webpack 项目，可能会经常见到require写法：

// Vue CLI 项目可用 const logo = require('@/assets/logo.png')

注意require是 Webpack 提供的模块系统语法，Vite 原生不支持。在 Vite 项目里看到require is not defined就是这问题，解决办法就是换 import 或 new URL。

还有一个更适合批量场景的 Vite 方案是import.meta.glob，可以把目录下所有图片一次性映射成对象，适合做批量资源统一管理，比如一个目录放了几十张图标，想全部引入时很省事。不过这个用在你确实需要"所有图片"的前提下，别为了帅而滥用。

4. 在线演示：一个工程验证所有结论

4.1 演示环境怎么搭

说再多不如跑一遍。我准备了一个可以直接在线运行的演示工程，不用本地装 Node、不用配环境，打开浏览器就能操作。

打开 StackBlitz 网站，点击新建项目，选择 Vue 模板（默认就是 Vite + Vue 3 的组合）。项目创建后，需要准备一张测试图片：随便找一张小 png，命名为logo.png，把它放到src/assets/目录下。同时在public目录下新建一个images子目录，也放一张logo.png（内容可以和 assets 里的相同，用不同名字也行，方便区分即可）。

最终目录结构类似这样：

src/ assets/ logo.png App.vue public/ images/ logo.png

4.2 演示代码：App.vue

下面这份App.vue覆盖了五种引用方式，复制进在线项目就能直接跑。

<template> <div class="demo"> <h2>Vue 静态资源路径演示</h2> <div class="row"> <p>1. 相对路径：./assets/logo.png</p> <img src="./assets/logo.png" alt="relative" width="80" /> </div> <div class="row"> <p>2. @ 别名：@/assets/logo.png</p> <img src="@/assets/logo.png" alt="alias" width="80" /> </div> <div class="row"> <p>3. 绝对路径：/images/logo.png（对应 public/images/）</p> <img src="/images/logo.png" alt="public" width="80" /> </div> <div class="row"> <p>4. 动态绑定：import 进来的图片</p> <img :src="logoUrl" alt="dynamic import" width="80" /> </div> <div class="row"> <p>5. style 中通过 @ 引入背景图</p> <div class="bg-box" /> </div> </div> </template> <script setup> import logo from '@/assets/logo.png' const logoUrl = logo </script> <style scoped> .demo { padding: 24px; } .row { margin-bottom: 16px; } .bg-box { width: 80px; height: 80px; border: 1px solid #ccc; background: url('@/assets/logo.png') center center / contain no-repeat; } </style>

几点说明：第 2 种和第 4 种本质上都是走@别名，只是引用方式不同；第 5 种在 Vite 下直接写@可以生效，如果你把这份代码搬到 Vue CLI 项目里，背景图那行建议改成~@/assets/logo.png，这就是前面章节反复强调的环境差异。

4.3 怎么看结果

运行起来之后，正常情况五张图都能显示。但光"能显示"还不够，建议你打开浏览器开发者工具，重点看两件事。

第一，看Elements面板里img标签编译后的src是什么。当使用相对路径和@时，你会发现src已经不是代码里写的那个路径，而变成了 base64 长串，或者带 hash 的文件名（取决于图片大小和构建配置）。这就是编译期路径换血最直观的证据。而绝对路径那一种，src依然是/images/logo.png，原样保留。

第二，可以试试执行一次构建。StackBlitz 的终端里跑npm run build，然后看dist目录结构：assets里的图片被处理进了dist/assets或类似目录，文件带 hash；public/images/logo.png则会原样出现在dist/images/logo.png。这个对比直接把两种存放姿势的差异摊开了。

5. 常见问题与排查技巧

5.1 问题一：打包后图片全部 404

这是被问得最多的一个问题。排查思路按顺序走，基本一两分钟内能定位。

第一步，打开打包产物目录，确认图片到底有没有被打包进去。如果dist目录里根本没有这个文件，说明路径解析有问题，检查代码里的路径是否存在、是否写错，优先换成@别名再试。如果文件在，但页面 404，问题大概率出在部署路径配置上。

第二步，看浏览器 Network 面板，找那条 404 请求，看它实际请求的 URL 是什么。比如你部署在https://example.com/myapp/，而请求地址是https://example.com/images/logo.png，那基本可以断定是代码里用了/开头的绝对路径，同时项目的publicPath或base没配置子路径。

5.2 问题二：动态拼接路径不生效

模板里写:src="'@/assets/' + name + '.png'"，图片死活不显示，控制台报 404 或者直接警告。原因已经重复好几次了：编译期无法解析动态字符串资源。

解决方案有三个方向。一是用 import 静态引入后，再根据条件切换；二是用 Vite 的new URL运行时解析；三是 Webpack 环境用require拼接完整路径。如果你有一整个目录的图片要动态展示，import.meta.glob（Vite）或require.context（Webpack）是更优雅的方案。

5.3 问题三：@ 在 style 里不生效

现象是 CSS 里写url('@/assets/bg.png')报错或图片 404，但同样是@，写在 template 里却没事。这本质上不是 Vue 的问题，而是构建链路上 CSS 解析器对路径的理解不同。

Webpack 项目里，解决办法就是给@加上~前缀，写成url('~@/assets/bg.png')。Vite 项目里先说确认resolve.alias配置正确，再确认 Vite 版本对 CSS 别名的解析行为，个别版本可能会对~@和@处理方式有细微差别，直接换个写法试试就能定位。

5.4 问题四：部署到子目录后全崩

项目要部署到https://example.com/myapp/这类子路径，结果样式丢失、图片 404。这通常是构建配置里缺了publicPath（Vue CLI）或base（Vite）。

Vue CLI 项目在vue.config.js里设置：

// vue.config.js module.exports = { publicPath: '/myapp/' }

Vite 项目在vite.config.js里设置：

// vite.config.js export default defineConfig({ base: '/myapp/' })

注意，配置base或publicPath只会影响构建时生成的资源路径，对于代码里手写的/images/logo.png这类绝对路径，它是不会自动帮你加前缀的。所以最省心的做法是：业务代码里少写站内绝对路径，统一用@或相对路径，让构建工具统一控制资源地址。

5.5 问题速查表

6. 一点实操心得

路径问题的核心，其实就是一句话：先分清资源放哪，再决定用哪种写法。我自己的习惯是，业务图片一律放src/assets，template和script里统一用@别名，Webpack 项目的style里用~@，Vite 项目直接用@。public目录只放需要原样访问的静态文件，而且很少在代码里通过绝对路径引用它。

另外还有个小技巧，每次打包部署后，别急着关终端，先看一眼构建产物目录，再打开浏览器 Network 检查图片请求。这两步加起来不超过一分钟，但能让你在问题刚冒头时就发现，不用等到线上用户反馈再手忙脚乱去复盘。

路径这东西，看着是小事，但它几乎会出现在你写的每一个组件里。花半小时把原理和坑位搞清楚，后续能省下大量排查时间。希望这篇笔记能给你省下这段弯路。