课程里那段交互视频要上线，作者发来 .h5p 文件，你在课程页面点「添加活动或资源」上传。几秒后页面停住，或者活动建好了、打开却提示「缺少内容类型」。问题多半出在运行环境、上传通道或包版本上。
上传之前：确认站点有 H5P 运行环境
Moodle 自带 H5P 活动，能在课程里播放 .h5p 内容，前提是站点装好对应的内容类型库。管理员先在「站点管理 → 插件 → 插件概述」确认 H5P 插件已启用，再看内容类型是否齐全。
环境没装好时，先别让老师反复试。插件未启用时，活动选择器里可能没有 H5P 入口；入口在、打开报错，排查方向不同。慕得的插件目录收录 3,104 个插件、60 个插件类型，可以在 插件目录 里按类型和分支筛选。
老师这一侧需要课程编辑权限，助教、访客只能看内容，不能新增或替换包。
把 .h5p 包上传到课程
上传有两个入口，按维护方式选。
- 在课程里新增 H5P 活动：一门课单独用，包和活动绑在一起。
- 先传到内容库再引用：多门课共用一个包，改一处、多处生效。
以课程内新增为例：开启编辑，在目标小节点「添加活动或资源」，选择 H5P 交互内容，填写名称，上传 .h5p，保存返回课程。上传后先预览，把交互走一遍，确认音频、字幕、跳转正常。
文件名尽量用英文、数字和下划线，不带空格和特殊符号。部分服务器处理中文文件名不一致，解析阶段就失败，简单文件名能少走一轮排查。
「缺少内容类型」：先刷新缓存，再判断是否真缺
这个报错有两种来源。一种是包里用到的内容类型站点没装，另一种是类型装好了、缓存还是旧的，Moodle 认不出这个包。第二种更常见，尤其在刚更新过插件、或从别的站点搬来包时。
先到「站点管理 → 插件 → H5P → 更新内容类型缓存」刷新一次，再回课程打开活动。仍然报错，就到内容类型列表对照包内类型，缺哪个装哪个，装完再刷新。
同一个报错对应两种原因。刷新缓存成本低，先做；确认类型确实缺失，再去装库。
替换课件：用新包覆盖原文件
作者改了内容，发来第二版 .h5p。这时不要新建活动。已有活动的链接、成绩项、完成条件、访问记录都指向原来那一条，新建会让旧链接失效，成绩也要重新关联。
做法是在原活动上替换：进入活动，点「编辑」，在包文件区域删除旧文件、上传新包，保存。包从内容库引用的，就去内容库替换那个文件，引用它的课程一起更新。
替换前把旧包留一份。在活动里导出原包，或下载一份放到课程资料区，再做一次课程备份。新包出问题能马上换回去。
常见失败原因与排查顺序
上传失败的表现有几种：进度条走完没反应、页面空白、提示文件过大、提示版本不匹配。常见原因如下。
- 文件过大：包体超过 PHP 的上传上限或 POST 上限，上传在服务端被截断。
- 执行时间不足：包体大、解压慢，请求在完成前被中断。
- 包本身损坏：导出中断或传输不完整，重新导出一份再试。
- 目录权限：moodledata 下的 H5P 目录不可写，上传后无法解压。
- 版本不匹配：包由更高版本的编辑器导出，站点已装的内容类型版本偏低。
前两项与服务器配置有关，需要管理员或托管方调整 php.ini 里的 upload_max_filesize、post_max_size、max_execution_time，改完重启服务再试。取值按站点规模和包体大小定，这里不给统一数字。包损坏由作者重新导出，目录权限看错误日志里的写入失败记录。站点没有专职运维时，可以走 慕得的服务 协助排查。
版本不匹配时，先看包需要哪个内容类型版本，把站点类型库更新到不低于该版本，再重新上传。站点暂时不能升级，可以让作者用相近版本重新导出，通常比升级整站快。
先在测试课程里把流程走一遍：装包、刷新缓存、替换、再从备份恢复。把每一步的入口和负责人写进课程维护说明。找参考样例时，H5P 课件目录 收录了 7,945 个课件，题型和交互形式比较全。
站点环境、上传限制或版本升级这几件事，最好在开课前理清负责人。把课程规模、包体大小和报错原文记下来，下一次换包能直接用。
