图片资源应按功能或业务域模块化拆分，如/logo/、/content/、/ui/、/placeholder/等目录，统一路径规范、小写命名，并通过构建工具实现跨模块安全引用与CI校验。
图片资源按模块拆分的合理目录结构
直接把所有图片丢进 /images/ 根目录，后期找图、迁移、协作时会迅速失控。模块化管理的核心是「按功能或业务域聚类」，不是按格式或尺寸。
-
/assets/images/logo/：只放品牌相关图标、矢量 logo、favicon 等，命名如logo-dark.svg、icon-twitter.svg -
/assets/images/content/：文章配图、产品截图、用户上传类内容图，建议按子路径再分，如/content/blog/2026-09/ -
/assets/images/ui/：按钮图标、加载动画、状态提示图（success.svg、error.png），优先用 SVG 或 inline data URL -
/assets/images/placeholder/：统一占位图，供onerror降级或开发阶段使用，如400x300.png
注意：所有路径都用相对路径，且以 HTML 文件所在位置为基准；避免混用 ./images/ 和 images/，否则在子目录页（如 /blog/post.html）中引用会失效。
HTML 中如何安全引用模块化图片
模块化后，src 值变长，但不能靠 JS 拼接或模板引擎硬塞——这会让静态分析、SEO 抓取、缓存失效变得不可控。
- 始终显式写全路径：
<img src="./assets/images/logo/logo-dark.svg" alt="深色Logo"> - 对 content 类图片，加
loading="lazy"是默认操作，但必须配srcset+sizes，否则移动端仍下大图 - UI 小图标建议内联 SVG，避免 HTTP 请求：直接写
<svg>...</svg>，或通过<use href="#icon-home"></use>复用 sprite - 禁止在
src里写变量占位符（如src="{{IMAGE_PATH}}/logo.png"），除非你明确在构建流程中做了预处理
模块间图片复用与版本控制难点
一个 logo 图片可能同时被首页、文档页、邮件模板引用。路径一改，全挂。这不是语义问题，而是工程稳定性问题。
立即学习“前端免费学习笔记（深入）”；
- 不要跨模块硬链接：比如在
/docs/下写../assets/images/logo/...，容易因目录层级变化断裂 - 推荐用构建工具做符号链接（如 Vite 的
public/目录或 Webpack 的resolve.alias），让@img/logo统一映射到物理路径 - 对第三方依赖中的图片（如 UI 库自带 icon），不要手动复制进项目，优先走
import或url()引入，由打包器处理 - SVG 图标建议用
<symbol>定义 +<use>调用，所有图标集中在一个icons.svg文件里，更新只需换一个文件
CI/CD 流程中如何校验图片模块完整性
本地跑得通，上线 404，八成是路径或大小写搞错了。Git 不区分大小写，但 Linux 服务器区分。
- 用
document.querySelectorAll('img')+naturalWidth === 0可在浏览器控制台快速扫出加载失败项 - CI 阶段可跑脚本检查所有
src路径是否存在：grep -o 'src="[^"]*"' *.html | sed 's/src="//;s/"$//' | xargs -I {} sh -c 'test -f {} || echo "MISSING: {}"' - 图片文件名强制小写 + 连字符（
user-avatar-2x.png），禁用空格、中文、特殊符号 - 对
/content/类动态图，建议在部署前生成 JSON 清单（content-index.json），前端通过 fetch 加载并校验存在性，而非盲目onerror
模块拆分本身不难，难的是路径一致性、构建链路适配和团队约定落地。一旦某个模块的图片开始被三个以上页面硬编码引用，就该考虑抽成共享资产并加自动化校验了。
