1. 从一次图片集体失踪说起：相对路径的三种基准线

前端项目本地跑得好好的，一打包部署到服务器，页面上所有图片齐刷刷变成裂图。打开控制台一看，请求路径是http://域名/assets/logo.png，可文件明明躺在src/static/images/里。这种场景我见过太多次，问题几乎都出在同一件事上：相对路径的"相对"到底相对于谁，开发者脑子里的基准线和浏览器实际使用的基准线不是同一条。

要彻底搞明白这件事，得先接受一个事实：在 Web 项目里，"相对路径"从来不是单一概念，它至少有三条不同的基准线，分别对应三种解析规则。

第一条基准线是当前 HTML 文档的 URL。这是浏览器解析<img src="...">、<a href="...">、CSS 里url(...)时默认采用的规则。假设页面地址是https://example.com/shop/detail/index.html，那么src="images/a.png"会被解析成https://example.com/shop/detail/images/a.png，而src="../images/a.png"则回退一级变成https://example.com/shop/images/a.png。注意这里有个容易翻车的点：如果页面地址末尾没有斜杠，比如https://example.com/shop/detail（很多路由框架生成的地址就是这样），浏览器会把detail当成文件名，基准目录变成/shop/，于是images/a.png解析结果就成了https://example.com/shop/images/a.png，和你的预期差了一整层。这就是为什么单页应用里用相对路径引用图片特别容易出问题——路由地址千变万化，基准线跟着乱跑。

第二条基准线是CSS 文件自身所在的目录。这一点很多人不知道：写在.css文件里的url(...)，基准线是那个 CSS 文件的位置，而不是引用它的 HTML 页面。比如css/main.css里写了background: url(../img/bg.png)，浏览器会以css/目录为起点回退一级，找到img/bg.png。这个规则本身是合理的，因为 CSS 可能被任意页面引用，以自身为基准才能保证稳定。但坑在于：如果你把 CSS 内联进 HTML 的<style>标签，基准线立刻切换成 HTML 文档的 URL，同一个url(../img/bg.png)解析结果完全不同。构建工具做 CSS 内联优化时如果没处理好路径重写，就会批量制造裂图。

第三条基准线是构建工具配置的 publicPath 或 base。这是打包阶段介入的规则，Webpack 的output.publicPath、Vite 的base、以及各类框架的路由base都属于这一类。它决定了最终产物里资源 URL 的前缀。如果配成/，资源从域名根目录找；配成./，则生成相对当前页面的路径；配成 CDN 域名，则全部指向外部。这条基准线最隐蔽，因为它不体现在源码里，而是构建时动态注入，出问题时你看源码完全正常，只有打开产物文件才能发现前缀被改掉了。

把这三条基准线理清楚，后面所有的路径问题都能对号入座。我习惯在排查时先问自己三个问题：这个路径写在 HTML 里、CSS 里还是 JS 里？它最终被哪个基准线解析？构建工具有没有动过它？三个问题答完，八成问题已经定位了。

提示：判断基准线最快的方法是打开浏览器开发者工具的 Network 面板，看实际请求的完整 URL，再和源码里的写法对比，差在哪一层就是哪条基准线在起作用。

2. 静态资源目录的摆放逻辑：为什么 public 和 assets 不能混着用

路径问题的根源往往不在路径本身，而在目录结构设计。我接手过不少项目，图片一会儿放src/assets，一会儿放public，一会儿又放static，最后连原作者都说不清某张图到底该从哪引。这种混乱不是懒，而是没搞懂不同目录在构建流程里的角色差异。

先说明白两类目录的本质区别。src/assets（或src/images）这类目录里的资源，是参与构建的。它们会被构建工具扫描、处理、重命名、加哈希，最终输出到产物目录。你在代码里import logo from './assets/logo.png'，拿到的不是原始路径，而是构建后带哈希的新路径，比如/assets/logo.a1b2c3.png。这种机制的好处是缓存友好——文件内容变了哈希就变，浏览器必然重新拉取；坏处是路径由构建工具决定，你不能硬编码。

public（Vue CLI 里叫static）这类目录里的资源，是不参与构建的。构建工具只做一件事：原封不动复制到产物根目录。你在代码里引用时必须用绝对路径/logo.png，因为它的位置在产物里是固定的。好处是路径可预测、可硬编码，适合放 favicon、robots.txt、第三方 SDK 的静态文件；坏处是没有哈希、没有压缩、没有 tree-shaking，改了内容浏览器可能还在用缓存。

这两类目录混用的典型症状是这样的：有人把图片放进了public/images/，然后在组件里写import img from '@/public/images/a.png'。构建工具会尝试处理这个 import，但 public 目录本就不该被 import，结果要么报错，要么被打包进 assets 又复制一份到根目录，产物里出现两份同样的图。还有人反过来，把需要哈希缓存的图放进了 public，上线后改了图发现用户看到的还是旧图，排查半天才发现是缓存没失效。

我的经验是给团队定一条硬规则：需要被 JS/CSS 引用的、需要构建优化的图，一律放src/assets；需要固定 URL 的、被外部系统引用的、不需要处理的文件，一律放public。这条规则一旦定下来，路径写法就自然分化了——assets 里的用 import 或相对路径，public 里的用绝对路径，不会再有中间态。

具体到不同框架，目录约定略有差异，但逻辑一致：

还有一类容易被忽略的资源是动态拼接的图片路径。比如根据用户 ID 显示头像，路径是/avatars/${userId}.png。这种图如果放在 assets 里，构建工具无法静态分析，不会帮你处理，运行时大概率 404。正确做法是把这类图放 public，用绝对路径拼接；或者用new URL(./avatars/${id}.png, import.meta.url)这种 Vite 支持的动态导入语法，让构建工具能识别。这个细节我在好几个项目里踩过，静态图正常、动态图全裂，最后都是目录放错导致的。

注意：public目录里的文件在开发环境和生产环境的访问路径可能不一致。开发时 Vite 把 public 映射到根路径，但如果你配了base，生产环境访问 public 文件也要带上 base 前缀，硬编码/logo.png会失效。稳妥做法是用import.meta.env.BASE_URL拼接。

3. 构建工具到底对路径做了什么：publicPath 与 base 的实战拆解

很多人对构建工具处理路径的认知停留在"配一下 publicPath 就行"，但真到出问题时，连 publicPath 影响的是哪些路径都说不清。我把构建工具对路径的干预拆成三个动作，理解了这三个动作，配置就不再是玄学。

第一个动作是重写 import 语句里的路径。当你在 JS 里import img from './a.png'，构建工具会拦截这个 import，把图片复制到输出目录、生成哈希文件名、然后把这个 import 替换成对新文件路径的引用。这个过程叫资源模块化。它只对能被静态分析到的 import/require生效。如果你写const p = './a.png'; import(p)，构建工具分析不出来，就不会处理，运行时按原路径找，必然失败。

第二个动作是给产物 URL 加前缀。这就是 publicPath（Webpack）或 base（Vite）的作用。它不改变文件在产物目录里的相对位置，只改变引用时拼在前面的字符串。配成/，产物里所有资源引用变成/assets/xxx.png；配成./，变成./assets/xxx.png；配成https://cdn.example.com/，变成完整外链。这个前缀会同时作用于 JS 里 import 的资源、CSS 里的 url、以及 HTML 里被处理的标签。

第三个动作是处理 CSS 里的 url。CSS 里的url(...)会被构建工具扫描，相对路径会被重写为基于产物结构的路径。但这里有个经典陷阱：如果 CSS 是通过@import引入的，或者被内联进 JS，路径重写的基准会变。我遇到过url(./img/a.png)在独立 CSS 文件里正常，一旦被 CSS-in-JS 方案处理就裂图，原因就是基准线从 CSS 文件变成了 JS 模块。

理解了这三个动作，再来看配置就清晰了。以 Vite 为例，base配置项直接决定第二个动作的前缀。默认值是/，适合部署在域名根目录。如果项目部署在子路径下，比如https://example.com/myapp/，就必须把 base 配成/myapp/，否则所有资源都会去根目录找，全部 404。这是子路径部署最常见的坑，而且开发环境往往正常（因为 dev server 默认在根），只有生产环境才暴露。

Webpack 的output.publicPath逻辑类似，但它还多一层__webpack_public_path__运行时变量，可以在代码里动态改。这个特性适合微前端或资源域名不固定的场景，但用不好会让路径彻底失控，我一般建议除非有明确需求，否则静态配置就好。

还有一个高频问题是开发环境和生产环境路径不一致。开发时 dev server 通常把资源挂在根路径，生产环境可能带 base 前缀或 CDN 域名。如果代码里硬编码了/assets/a.png，开发正常、生产裂图。解决办法是统一用构建工具提供的环境变量拼接，Vite 用import.meta.env.BASE_URL，Webpack 用process.env.PUBLIC_URL（CRA）或自定义变量。这样路径前缀跟着配置走，不会写死。

我个人的习惯是：项目初始化时就把 base 配好，哪怕暂时部署在根目录也留好子路径的可能；所有需要拼接路径的地方统一走环境变量，绝不硬编码；上线前用npm run build后本地起个静态服务器，把产物按真实部署路径跑一遍，确认没有裂图再发布。这一步多花五分钟，能省掉上线后半夜排查的两小时。

4. 图片上传与保存：从表单到落盘的完整链路

前面聊的都是"引用已有图片"，但 Web 项目里还有一大类场景是用户上传图片并保存，这条链路的路径问题更复杂，因为它涉及前端、后端、存储三层，每层都有自己的路径概念。

先看前端这一层。用户通过<input type="file">选图后，拿到的是File对象，它没有真实路径，只有一个name和内存里的数据。想在页面上预览，得用URL.createObjectURL(file)生成一个blob:开头的临时地址，或者用FileReader读成 base64。这两个地址都不能直接存进数据库——blob 地址在页面刷新后就失效，base64 体积巨大且不适合当路径。我见过有人把 blob 地址存进后端，结果用户下次登录头像全没了，就是这个原因。

正确的做法是前端把File通过FormData发给后端，由后端决定最终存储路径。这里有个细节：FormData上传时不要手动设置Content-Type，让浏览器自动带上 boundary，否则后端解析会失败。这个坑我在早期项目里踩过，手动设了multipart/form-data反而导致文件收不到。

后端这一层是路径问题的核心。收到文件后，要决定三件事：存到哪、叫什么名、怎么返回访问地址。

存到哪，取决于部署架构。单机部署可以存本地磁盘，比如uploads/目录；多机或容器化部署必须用对象存储或共享存储，否则用户上传的图在 A 机器上，下次请求打到 B 机器就 404。这个决策要在项目初期定，后期迁移成本很高。

叫什么名，是安全性和可维护性的关键。绝对不能用用户上传的原始文件名，原因有三：一是可能重名覆盖，两个用户都传avatar.png就冲突了；二是原始文件名可能包含路径穿越字符（如../），被恶意利用；三是中文名、特殊字符在不同系统上编码不一致，容易出乱码。标准做法是生成唯一文件名，常见方案是 UUID、时间戳加随机数、或内容哈希。我一般用日期目录 + UUID + 原扩展名，比如2024/06/15/a1b2c3d4.png，既保证唯一，又方便按日期归档和清理。

怎么返回访问地址，是前后端约定的接口。后端存完文件后，要返回一个前端能直接用的 URL。这个 URL 有两种形态：绝对路径（如/uploads/2024/06/15/a1b2c3d4.png）和完整 URL（如https://cdn.example.com/uploads/...）。如果图片和前端同域，返回绝对路径即可；如果用了独立图片域名或 CDN，必须返回完整 URL，否则前端拼不出来。我建议后端统一返回完整 URL，前端拿到直接用，省去拼接逻辑，也避免前端不知道图片域名的问题。

存储路径和访问路径的映射关系也要理清。文件实际存在磁盘的/data/uploads/2024/06/15/a1b2c3d4.png，但对外访问是/uploads/2024/06/15/a1b2c3d4.png，中间靠 Web 服务器的静态资源映射或后端的静态文件中间件打通。这个映射配错，就会出现"文件明明存进去了，访问却 404"的情况。排查时先确认文件在磁盘上的真实位置，再确认访问 URL 对应的映射规则，两边一对就能找到断点。

还有一个容易被忽略的点是图片的后续处理。用户上传的原图可能几 MB，直接展示会拖慢页面。通常要在后端做压缩、生成缩略图、转格式（如转 WebP）。这些处理会生成新文件，新文件的路径也要一并返回给前端。我习惯在返回结构里同时给出原图、缩略图、不同尺寸的 URL，前端按场景选用，避免每次都加载大图。

注意：上传目录要设置合理的权限，禁止执行权限，防止上传的文件被当作脚本执行。同时要限制文件类型和大小，只允许图片扩展名，并在服务端校验文件头，不能只信前端传来的 MIME 类型。

5. 跨环境路径排查：从本地到线上的一套定位方法

路径问题最折磨人的地方在于环境差异——本地好好的，测试环境正常，一到生产就裂图。这种问题靠猜是猜不出来的，得有一套系统的排查方法。我把自己常用的排查链路整理成四步，基本能覆盖九成以上的路径故障。

第一步，确认请求的实际 URL。打开浏览器开发者工具的 Network 面板，筛选 Img 或 XHR，找到失败的请求，看它的完整 URL 是什么。这一步的目的是拿到"浏览器实际请求了什么"，而不是"你以为请求了什么"。很多时候一看 URL 就明白了，比如请求打到了https://example.com/assets/a.png，但你的图在https://example.com/myapp/assets/a.png，明显是 base 没配对。

第二步，对比源码写法与产物写法。如果实际 URL 和预期不符，去产物目录里找到对应的文件，看构建后路径被改成了什么。比如源码里是import img from './a.png'，产物里可能变成了/assets/a.a1b2c3.png。如果产物里的路径前缀不对，问题在构建配置；如果产物里根本没有这个文件，问题在资源没被正确打包。

第三步，验证文件是否真实存在。有时候路径完全正确，但文件就是不在那个位置。去服务器上ls一下产物目录，确认文件在不在。我遇到过构建时因为.gitignore把某类图片排除了，本地有、CI 构建时没有，产物里自然缺文件。还有大小写问题——本地 macOS 文件系统不区分大小写，Logo.png和logo.png都能访问，部署到 Linux 服务器就区分了，直接 404。这类问题在 Network 面板里看 URL 大小写和实际文件名对比就能发现。

第四步，检查缓存和 CDN。如果文件存在、路径也对，但用户还是看到旧图或裂图，多半是缓存问题。浏览器缓存、CDN 缓存、服务端缓存都可能。排查时先强制刷新（Ctrl+Shift+R）绕过浏览器缓存，再检查 CDN 的缓存规则，最后看服务端有没有设长缓存。带哈希的文件名天然免疫这个问题，没带哈希的就要靠缓存头控制。

把这四步串起来，就是一条完整的排查链路：看请求 URL → 对比产物 → 验证文件 → 排除缓存。每一步都有明确的判断依据，不会陷入"改一下试试"的盲目循环。

再补充几个跨环境的特殊坑。开发环境用 dev server，生产环境用 Nginx，两者的路径处理规则不同。dev server 通常有 history fallback，任何路径都返回 index.html，所以相对路径可能"看起来正常"；Nginx 如果没配 try_files，刷新子路由就 404。Docker 部署时，构建阶段和运行阶段的目录结构可能不同，构建产物复制到运行镜像时路径变了，引用就会失效。子路径部署是最常见的生产环境坑，本地根路径开发，上线放到/app/下，所有绝对路径全废，必须靠 base 配置解决。

我个人的经验是，上线前一定要在接近生产的环境里完整走一遍。不是本地npm run dev，而是npm run build后用静态服务器按真实路径跑。这一步能提前暴露 90% 的路径问题，比上线后救火划算得多。另外，团队里最好统一路径规范，写进项目文档，新人进来照着做，能少踩很多重复的坑。

6. 几个让我印象深刻的真实翻车案例

理论讲再多，不如看几个实际翻车的例子。下面这几个案例都是我在不同项目里真实遇到或协助排查过的，每个都对应前面讲过的某条规则，看完你会对路径问题有更具体的体感。

案例一：子路径部署导致的全面裂图。某项目本地开发一切正常，部署到服务器的/shop/子路径下后，所有 JS、CSS、图片全部 404。打开 Network 一看，请求全打在https://example.com/assets/...，而实际资源在https://example.com/shop/assets/...。原因就是构建时 base 用了默认的/，没改成/shop/。改一行配置重新构建，问题解决。这个案例的教训是：部署路径不是根目录时，base 必须显式配置，而且要在项目初期就确认部署路径，别等上线才发现。

案例二：CSS 内联导致的背景图消失。某项目为了优化首屏，把关键 CSS 内联进了 HTML。结果内联的那部分 CSS 里，url(../img/bg.png)全部失效。原因是内联后基准线从 CSS 文件变成了 HTML 文档，../回退的层级不对了。解决办法是内联时把相对路径重写成绝对路径，或者干脆把背景图放 public 用绝对路径引用。这个案例说明：CSS 的基准线规则会随引入方式改变，做构建优化时要特别小心。

案例三：动态拼接路径的 404。某后台系统要根据商品 ID 显示图片，代码写的是src={'/images/' + id + '.png'}。开发时图片放在 public 里，正常；后来有人把图片挪到了 assets，构建后路径带了哈希，动态拼接的路径自然找不到。这个案例的教训是：动态路径的图片必须放 public，因为构建工具无法分析运行时才确定的路径，不会帮你处理哈希和重写。

案例四：大小写引发的血案。某开发在 Mac 上开发，图片命名Banner.png，代码里写banner.png，本地正常。部署到 Linux 服务器后，这张图 404。原因是 macOS 文件系统默认不区分大小写，Linux 区分。排查时对比 Network 里的 URL 和服务器上的实际文件名，一眼就看出大小写不一致。这个坑很隐蔽，因为本地永远复现不了，只能靠规范约束——图片命名统一小写，代码引用严格匹配。

案例五：缓存导致的"改了没生效"。某次运营反馈换了 banner 图，但用户看到的还是旧图。排查发现图片没带哈希，文件名也没变，浏览器和 CDN 都缓存了旧版本。解决办法是给图片加版本号或哈希，或者配置合理的缓存失效策略。这个案例说明：不带哈希的静态资源，缓存策略必须配套设计，否则更新就是一场和缓存的拉锯战。

这几个案例有个共同点：问题都不在代码逻辑，而在路径规则和环境差异。代码逻辑错了，本地就能测出来；路径规则错了，往往只在特定环境暴露。所以对待路径问题，心态上要把它当成"环境适配"问题，而不是"代码 bug"，排查时优先怀疑环境差异，而不是反复读代码。

提示：给团队建一个"路径问题排查清单"，把上面这些案例对应的检查项列进去，新人遇到裂图先过一遍清单，能大幅缩短排查时间。

7. 一套可以直接抄的路径规范

聊了这么多原理和案例，最后落到可执行层面。下面这套规范是我在多个项目里沉淀下来的，直接抄去用，能避开绝大多数路径坑。

目录约定：src/assets放参与构建的图片、字体、图标；public放 favicon、robots.txt、需要固定 URL 的文件、动态拼接路径的图片。两者不混用，不互相引用。

引用方式：assets 里的资源用import引入，让构建工具处理；public 里的资源用绝对路径/xxx引用，需要带 base 时用环境变量拼接。CSS 里的背景图优先放 assets，用相对路径，避免内联。

命名规范：所有图片文件名统一小写，用短横线分隔，不含中文和特殊字符。上传的图片由后端生成 UUID 文件名，不用原始名。

构建配置：项目初始化时确认部署路径，base/publicPath 按实际路径配置。所有需要拼接路径的地方走环境变量，不硬编码。

上传链路：前端只负责选图和预览，上传原始 File；后端负责生成唯一文件名、决定存储位置、返回完整访问 URL；存储路径和访问路径的映射关系明确并测试。

上线检查：每次上线前用build产物在接近生产的环境跑一遍，重点检查子路径、动态图、CSS 背景图、上传图四类场景。

这套规范不复杂，难的是坚持执行。我见过太多项目前期图省事乱放，后期图片多了想整理都无从下手。路径这件事，前期多花十分钟规范，后期能省几十小时排查。

最后分享一个我常用的小技巧：在项目里加一个简单的路径自检脚本，构建后扫描产物里的所有资源引用，逐个检查文件是否存在。这个脚本几十行就能写完，但能在 CI 阶段就拦住大部分路径问题，比上线后才发现强太多。具体思路是遍历产物目录里的 HTML、CSS、JS，提取所有资源 URL，去掉域名和 base 前缀后，检查对应文件在产物里是否存在，不存在的就报错。这个脚本我放在好几个项目里，拦下过不少因为重构、改名、移动目录导致的路径断裂。

路径问题说到底是个细致活，没有多高深的技术，但需要你对每条规则都心里有数，对每个环境差异都保持警惕。把上面这些规则和案例吃透，下次再遇到裂图，你就能像老手一样，五分钟定位，而不是对着代码干瞪眼。