QA WIKI（常见问题）
本页从项目 GitHub Wiki挑选仍有用的排障问题，并按当前 SDK重新说明；不照搬 2022 年 Wiki 中旧版本的包名和参数。先查看浏览器 Console、Network、媒体响应和 on_error_callback，再按现象排查。
MP4 一直加载：moov、mdat 和 HTTP Range 是什么？
MP4 的 mdat 保存媒体数据，moov 保存定位和播放这些数据所需的索引、时间信息。moov 放在 mdat 前面，普通 HTTP 客户端能更早拿到索引。moov 在文件尾不等于必然不能播放：服务器和播放链路支持字节范围请求时仍可能正常播放；但它是启动慢或探测失败的常见原因。文件与 HTTP 都要检查：
ffprobe -v trace -i input.mp4 2>&1 | grep -E "type:'(moov|mdat)'"
curl -sS -D - -o /dev/null -H 'Range: bytes=0-1023' 'https://example.com/video.mp4'Range 请求应返回 206 Partial Content 和有效的 Content-Range。如果文件本身有效，只需把 moov 前置，可无损封装到新文件：
ffmpeg -i input.mp4 -map 0 -c copy -movflags +faststart output-faststart.mp4同时确认 URL 可访问、响应真的是 MP4 而非 HTML 错误页，以及浏览器/所选内核支持视频编码。原始资料见 Wiki 的 MP4 问答和转码指南。
首帧 ready 了，为什么画面还是黑的？
on_ready_show_done_callback 表示首帧已可用，不代表已经开始播放。auto_play: false 时，需要用户点击后调用 play()；也可设置 auto_play: true，但仍受浏览器自动播放策略约束。媒体的第 0 帧本身也可能是黑色：用 ffmpeg -i input.mp4 -frames:v 1 first.png 查看，然后尝试播放或向后 Seek。根目录 Demo 的 Autoplay: Off 意味着点完 Create + Load 还要点 Play。仓库样例 videos/vr.mp4 的第 0 帧为黑色，随后才出现画面。
为什么自动播放没声音，或者 play() 被拒绝？
浏览器通常会阻止用户交互前的有声播放。可先静音启动，再让用户主动打开声音。自动播放策略拒绝不等于解码或网络错误。ignore_audio: true 是跳过音频链路，不是以后可以重新开声的静音方式。本条按当前 auto_play API 更新了 Wiki 的自动播放问答。
Demo 或 WASM 初始化失败怎么办？
请用 HTTP(S) 提供页面，不要直接用 file://。在 Network 中确认 h265web.js、h265web_wasm.js、h265web_wasm.wasm，以及显式使用历史内核时的 ext* 文件，是否请求到正确地址和状态。服务器即使返回 200，若响应体是 HTML 兜底页，仍不是正确 WASM；还要核对响应内容和 application/wasm MIME。JS/WASM 文件应来自同一次构建。多线程链路如果提示缺少 SharedArrayBuffer，检查安全上下文、页面跨源隔离响应头（Cross-Origin-Opener-Policy: same-origin、Cross-Origin-Embedder-Policy: require-corp），以及跨域子资源的 CORS/CORP。不要把旧 Wiki 中的 dist、missile-* 包建议直接套用到当前构建。原始问题见 Wiki 初始化失败系列。
VLC 可以播，浏览器却不能播？
VLC 与浏览器的解封装、解码器、MIME、自动播放和 CORS 限制并不相同。先用 ffprobe -hide_banner input.mp4 看容器、视频和音频编码，再核对实际 HTTP 响应、video_probe_callback 与 on_error_callback。若目标是原生/MSE HEVC MP4 链路，检查视频 sample entry 是否为 hvc1；-tag:v hvc1 -movflags +faststart 重封装只可能帮助编码本身已经兼容的文件。MediaSource.isTypeSupported() 只能提示能力，不能证明某个文件一定能播。浏览器不支持原生链路时，SDK 可能选择 WebCodec 或 WASM。参见 Wiki 的编码/硬解问答。
HEVC 裸流打不开？
确认 URL 实际返回裸流数据，后缀是可识别的 .265、.h265 或 .hevc。使用真正可访问的 HTTP(S) URL，或确认相对路径是从页面正确解析的；先看 Network，再改解码设置。裸流不是 MP4，没有 moov box，也不自带 MP4 音轨。参见 Wiki 裸流问答。
VR360 视频播放时遇到 CORS 错误？
协议、主机名或端口有任一不同，就属于不同源。媒体服务器需允许页面来源；要检查重定向后的最终媒体/分片响应，不能只看第一跳。VR360 画面需要从 video 读取画面，因此跨源视频必须有允许读取的 CORS 响应。初始化时请求 VR360 但 CORS 加载失败，播放器可在同一播放链路重试一次普通平面视频，并报告 VR_SOURCE_CORS。已经以非 CORS 方式加载的视频，也不能在播放中无损切到 VR360。详见 VR360 视频播放 API及 Wiki CORS 问答。
HEVC 或 VR 卡顿、内存不足？
先确认实际选中的内核、源分辨率/码率/帧率，以及设备和浏览器的原生编码能力。WASM/软解需要 CPU 和内存；只缩小输出 canvas 不会降低源视频解码成本。先用单实例和更简单的媒体复测，再看内存压力和 Console 错误。ERP 一帧要覆盖整个球面，放大视角后源分辨率不足也会显得模糊。不要把 Wiki 的旧固定码率建议或 missile-256mb 当成通用门槛。参见 Wiki 播放卡顿问答。
VR360 应该用什么视频和直播地址验收？
使用单目等距柱状全景视频（简称 ERP，画面通常为 2:1）。projection: 'erp360' 是启用 VR360 观看方式的配置值，不能把普通平面 MP4 变成全景。根目录 index.html 已提供 VR360 点播预设和直播地址模板；直播模板必须先有实际推送的 VR360 流。HLS 请选 hls_strategy: 'auto' 或 'mainline'，'legacy' 仍为平面。原生 WebRTC 可在协商后显示 VR360；WebCodec/WASM 编码 WebRTC 链路还需服务端支持 API 文档所述的独立协议。
仍未解决，反馈时提供什么？
请提供页面 URL、去掉密钥的媒体 URL、浏览器/系统、所选内核、build() 配置、Console/Network 错误、ffprobe 摘要、是否开启自动播放，以及已知可播放小样例的对比结果。不要公开账号、口令或私有流 token。GitHub Wiki 和 Issues 仍可查看历史资料并提交问题。