媒体资源路径必须用根相对路径，即以/开头，统一放在/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 一致，但容易被漏掉。
