本文详解 Vue/React 等现代前端项目中 SVG 通过 <img> 标签引入时在本地正常、部署后失效的根本原因，并提供标准化路径处理、公共目录配置、构建优化等专业级解决方案。
本文详解 vue/react 等现代前端项目中 svg 通过 `` 标签引入时在本地正常、部署后失效的根本原因，并提供标准化路径处理、公共目录配置、构建优化等专业级解决方案。
在现代前端工程中（如 Vite、Vue CLI、Create React App），将 SVG 作为 <img> 的 src 引入是一种常见做法，例如：
<img src="/src/assets/logo-bookmark-white.svg" alt="Logo" />
该写法在本地开发服务器（如 vite dev 或 npm start）下通常能正常显示，但一旦部署到 Vercel、Netlify 或 GitHub Pages，图片便“消失”——浏览器控制台常报 404 错误，提示 Failed to load resource: the server responded with a status of 404 ()。
根本原因在于：路径语义与构建产物不匹配。
/src/assets/logo-bookmark-white.svg 中的 /src/ 是源码目录结构，而构建工具（如 Vite、Webpack）默认不会将 src/ 目录原样输出到生产环境。打包后的静态资源通常被复制、哈希重命名，并集中存放于 dist/assets/（Vite）或 build/static/（CRA）等目录下。因此，以 /src/ 开头的绝对路径在部署后完全无效——服务器根本找不到该路径。
✅ 正确做法是遵循构建工具的静态资源处理规范：
✅ 方案一：使用相对路径（推荐用于项目内 SVG）
将 SVG 文件置于 src/assets/ 后，用相对于当前组件文件的相对路径引用（注意：不是相对于 public/）：
<!-- 假设此 HTML 在 src/components/Header.vue 或 src/App.jsx 中 --> <img src="./assets/logo-bookmark-white.svg" alt="Logo" />
⚠️ 注意：./assets/ 中的 . 表示“当前模块所在目录”，Vite / Webpack 会自动解析并将其纳入构建流程，生成正确的哈希路径和资源引用。
✅ 方案二：放入 public/ 目录（适用于需保持原始路径的资源）
将 SVG 移至 public/assets/logo-bookmark-white.svg，然后使用根绝对路径（不带 src/）：
<img src="/assets/logo-bookmark-white.svg" alt="Logo" />
✅ public/ 下的文件会被原样复制到 dist/ 根目录，不经过构建处理，因此 /assets/ 在部署后可直接访问。
❌ 避免的错误写法
- <img src="/src/assets/xxx.svg" /> → 源码路径，部署后 404
- <img src="src/assets/xxx.svg" /> → 相对路径但指向不存在的 src/ 子目录
- 依赖外部图床（如 Imgur）→ 不可控、无缓存策略、影响加载性能与隐私合规
? 验证与调试建议
- 构建后检查 dist/（或 build/）目录结构，确认 SVG 是否存在及实际路径；
- 浏览器开发者工具 → Network 标签页，查看 SVG 请求的 Actual Request URL 和响应状态；
- 在 Vercel/Netlify 控制台查看构建日志，确认资源是否被正确拷贝或处理。
? 进阶提示：SVG 作为组件使用（更优实践）
若需交互、动态着色或复用，推荐将 SVG 转为 Vue/React 组件（如 LogoIcon.vue），直接导入使用，既能类型安全，又支持 props 控制尺寸/颜色：
<!-- LogoIcon.vue -->
<template>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 30" v-bind="$attrs">
<path fill="currentColor" d="M10 10h10v10H10z"/>
</svg>
</template><!-- 使用 --> <LogoIcon class="w-8 h-8 text-white" />
综上，SVG 部署失效本质是路径管理与构建配置的认知偏差。坚持使用 public/（静态不变资源）或模块化相对导入（动态可维护资源），配合构建工具约定，即可彻底规避该问题。
