技术文档里的多媒体能力：图片、视频、音频、3D 和可运行 Demo

传统技术文章通常是文字、代码块和几张截图。对复杂知识来说，这不够。性能、动画、协议状态、3D 场景、AI 流式输出，都更适合用可交互内容解释。

可以增强哪些内容

• 图片：点击大图、缩放、键盘关闭、移动端手势。
• 视频：用来展示交互过程、部署过程或故障复现。
• 音频：适合播客、朗读、语音反馈和 TTS 示例。
• 3D：展示模型、机器人结构、坐标系、传感器视角。
• 在线 Demo：让读者直接操作 WebSocket、IntersectionObserver、Canvas、Three.js 等能力。

设计原则

1. 媒体服务内容，不要抢正文注意力。
2. 移动端优先，控制高度和触控区域。
3. 大资源懒加载，避免首页和文章首屏变慢。
4. 所有外链资源都要考虑失效和隐私问题。

博客当前落地点

本博客已经具备图片预览、音视频增强、文章阅读进度、在线实验室、按需加载的 Three.js 文档预览和 EPUB/TXT 阅读器基础能力。文章编辑器只接受白名单 Demo 类型，不执行作者提供的任意脚本。

图片：说明结构并控制首屏成本

截图和架构图应有能表达信息的替代文本；纯装饰图使用空 alt。给图片明确宽高或 aspect-ratio，减少加载时布局跳动。首屏关键图不要盲目延迟加载，长文下方图片才适合 loading="lazy"。点击放大需支持键盘关闭、焦点和移动端缩放。

<figure>
  <img src="/media/request-flow.webp"
       alt="浏览器请求依次经过 CDN、网关和内容服务"
       width="1280" height="720" loading="lazy" decoding="async">
  <figcaption>图 1：公开页面的请求路径。</figcaption>
</figure>

音视频：原生控制、字幕和转录

默认优先使用 <audio controls> / <video controls>，让用户能暂停、拖动和调节音量。视频应提供准确字幕或说明性字幕；声音承载关键信息时，另给文字转录。自动播放会打断阅读，不要作为默认。preload="metadata" 通常可减少初始传输，但最终行为仍受浏览器和服务端影响。

<video controls preload="metadata" poster="/media/demo-poster.webp">
  <source src="/media/demo.mp4" type="video/mp4">
  <track kind="captions" src="/media/demo.zh-CN.vtt"
         srclang="zh-CN" label="简体中文" default>
  <a href="/media/demo.mp4">下载视频</a>
</video>
<p><a href="/media/demo-transcript.html">阅读本视频文字稿</a></p>

字幕使用 WebVTT，语言标签、资源 MIME 和路径要正确；跨源媒体还要配置合适的 CORS。多个 <source> 应填写真实格式，不能只改扩展名。音频也要有标题、来源和文字稿，避免播放控件成为唯一信息渠道。

3D：先交代模型，再加载渲染器

3D 适合展示结构、空间关系和可旋转对象。给出静态 poster、模型说明和下载/查看替代链接；模型进入视口或用户主动打开后再加载，并控制移动端的贴图、几何复杂度和像素比。<model-viewer> 可展示受支持的 glTF/GLB 模型并提供相机交互，但它不是任意三维文件解码器；其它格式需要经过受控转换或使用适配渲染器。

<model-viewer src="/media/robot.glb"
  alt="树莓派小车的外壳和传感器安装位置"
  poster="/media/robot-poster.webp" loading="lazy"
  camera-controls touch-action="pan-y">
</model-viewer>
<a href="/media/robot.glb">下载 GLB 模型</a>

本博客内置的 three Demo 以轻量几何体演示场景、相机、材质和光照；点击后才加载渲染器，并支持桌面/触屏拖动与模型切换。当前版本不承诺解析作者上传的任意 GLB、GLTF、OBJ 或 STL 文件；这类资源需要单独的格式白名单、尺寸限制、隔离解析和失败预览。

把 viewer 作为按需依赖，不要让所有文章都下载它；为容器设置稳定尺寸，保留加载中、失败和无脚本时的替代内容。除非交互确有需要，不要默认持续自动旋转。

可运行 Demo：与博客主站隔离

静态白名单 Demo（CSS、Canvas、受控浏览器 API）可以在本页运行；执行文章作者代码时，不要把字符串 eval 到博客主文档。优先在独立来源的 iframe/preview origin 运行，设置最小 sandbox 权限、CSP、资源额度和消息协议。后端执行用户代码需要真正的进程/容器隔离；普通 iframe 不是服务器沙箱。

<iframe title="可交互的布局示例"
  src="https://preview.example/demo/grid"
  loading="lazy" sandbox="allow-scripts"
  referrerpolicy="no-referrer"></iframe>

只给 iframe 增加 Demo 实际需要的 sandbox token，并优先使用与博客不同的 origin。父子窗口通过 postMessage 通信时验证来源、消息类型和字段，不传登录凭证。后台和渲染器都应使用 Demo 类型白名单，Markdown 不能成为任意脚本执行入口。

编辑器和资源治理

后台媒体块至少应保存类型、资源地址、替代文本/标题、字幕或转录、封面、宽高、来源、访问权限和加载方式。上传流程校验真实格式与大小，使用随机存储名并限制访问；文档下架时也要定义媒体是否同时下架。外链资源可能失效，也可能向第三方暴露读者的 IP 或 Referer；重要资料要评估本地托管与版权许可。

多端验收清单

• 手机竖屏、窄屏和低性能设备下，正文先可读，媒体不溢出。
• 视频字幕、文字稿、播放/暂停和音量都可操作；媒体失败时有明确回退。
• 3D 和 Demo 有稳定尺寸、加载/失败状态与非交互替代内容。
• 键盘焦点不被 iframe/弹窗吞掉；减少动态效果时关闭非必要旋转和视差。
• 检查 MIME、缓存策略、CSP、iframe 权限及受限媒体访问授权。

官方参考

• MDN <video>
• MDN <track> 与 WebVTT
• MDN <iframe> 和 sandbox
• Google <model-viewer> 文档
• Google <model-viewer> 懒加载示例