HTML文件目录标准化：大型项目图片、音频、视频等媒体资源分类维护的方法

媒体资源路径必须用根相对路径，即以/开头，统一放在/media/下并按类型+业务维度分二级目录，HTML中source标签的src也需为根相对路径，构建阶段须自动校验路径有效性。

media 资源路径必须用根相对路径

大型项目里，img、video、audio 的 src 如果用相对路径（比如 ./assets/video/intro.mp4），一旦 HTML 文件挪动目录层级，所有链接立刻失效。这不是浏览器问题，是路径解析规则本身决定的。

根相对路径（以 / 开头）能绕过这个陷阱：所有资源都从网站根目录开始找，和 HTML 文件位置无关。比如统一约定媒体资源放在 /media/ 下，那么无论页面在 /product/detail.html 还是 /blog/2026/post.html，都能稳定写成：

<img src="/media/logo.png" alt="logo">
<video src="/media/demo.mp4" controls></video>
<audio src="/media/sound.mp3" controls></audio>

• 部署到子路径（如 https://example.com/app/）时，需配合构建工具配置 publicPath，否则 /media/ 会指向域名根而非应用根
• 本地直接双击打开 HTML 文件时，/media/ 会失败（file:// 协议不支持根路径），开发阶段建议用本地服务器（如 npx serve）跑
• 不要混用：一个项目里别一部分用 ../assets/，一部分用 /media/，维护成本会指数级上升

按类型+业务维度分二级目录

只建 /media/images、/media/videos 这种扁平结构，半年后就会陷入“找一张图要翻 17 页”的境地。真正可维护的结构得带业务语义。

推荐模式：/media/{type}/{domain}/{name}，例如：

立即学习“前端免费学习笔记（深入）”；

/media/images/product/iphone-15-pro-hero.jpg
/media/images/avatar/user-default.png
/media/videos/onboarding/welcome-v2.webm
/media/audio/notification/success.ogg

• {type} 固定为 images、videos、audio、icons（不用 img 或 pic，避免缩写歧义）
• {domain} 是业务模块名，不是技术目录（如不用 components，而用 checkout、profile）
• 文件名用 kebab-case，不含空格和中文，版本号用后缀（welcome-v2.webm 而非 welcome(2).webm）

HTML 中 source 标签的 src 必须单独配置

video 和 audio 里嵌套的 source 标签，其 src 不继承父级路径。即使 video 写了 src="/media/demo.mp4"，里面的 <source src="demo.webm"> 仍会从当前 HTML 所在目录找——这是最容易踩的坑。

正确做法：所有 source 的 src 也必须是根相对路径，并与 video/audio 的主 src 同级管理：

<video controls poster="/media/videos/onboarding/cover.jpg">
  <source src="/media/videos/onboarding/welcome.mp4" type="video/mp4">
  <source src="/media/videos/onboarding/welcome.webm" type="video/webm">
  您的浏览器不支持 video 元素。
</video>

• poster 属性同样适用根相对路径，且图片格式优先选 .jpg 或 .png（.webp 在部分旧版 Safari 中不支持）
• 不同格式文件必须放在同一业务子目录下，避免跨目录引用导致构建工具无法正确收集依赖
• Webpack/Vite 的 html-loader 需显式配置 sources.list 支持 source 标签，否则打包时这些 src 会被忽略（见知识库中 loader 配置示例）

构建阶段自动校验媒体路径有效性

靠人肉检查 src 是否拼错、文件是否存在，永远会漏。必须让构建流程拦截。

在 Webpack 或 Vite 插件中加一层扫描逻辑，对每个 HTML 文件做两件事：

• 提取所有 img[src]、video[src]、audio[src]、source[src] 的路径
• 检查对应文件是否真实存在于 /media/ 目录下，不存在则报错中断构建

这比运行时 404 更早暴露问题。尤其当设计师交付新视频却忘了同步上传文件时，CI 流水线会立刻卡住，而不是等上线后用户反馈“视频打不开”。

注意：校验脚本必须处理 srcset（响应式图片）和 picture 里的多个 source，它们的路径规则和单个 src 一致，但容易被漏掉。