在moodle自定义页面中直接输出`$course->summary`时，嵌入的图片无法正常显示，仅显示文件名和占位图标——这是因为摘要中的图片url未经过上下文重写，需调用moodle的文件url重写机制或渲染器方法才能正确解析。
Moodle将课程摘要（summary）中的图片以插件文件（pluginfile.php）形式存储，并依赖上下文（context）进行安全访问控制。若在非标准课程页面（如自定义PHP页面、仪表板模块或外部渲染逻辑）中直接使用 format_text($course->summary)，Moodle无法自动识别当前内容所属的课程上下文，导致图片URL未被重写为可访问的路径，最终浏览器加载失败，仅显示文字描述与默认图标。
✅ 正确做法：两种推荐方案
方案一：使用课程渲染器（推荐，语义清晰、兼容性强）
Moodle 3.9+ 提供了 coursecat_helper 渲染器（注意：实际应为 core_course_renderer 或专用摘要处理方法；但官方推荐方式是调用 $PAGE->get_renderer('core_course') 或使用 get_course_formatted_summary() 的封装逻辑）。更稳妥且向后兼容的做法如下：
global $CFG, $PAGE;
require_once($CFG->dirroot . '/course/lib.php');
// 获取课程上下文
$context = context_course::instance($course->id);
// 使用 format_text 并显式传入上下文，确保文件URL重写
$summary = format_text(
$course->summary,
$course->summaryformat,
['context' => $context, 'overflowdiv' => true, 'filter' => true]
);
echo $summary;✅ 优势：自动启用过滤器（如media、algebra）、支持格式转换（HTML/Markdown等），并强制绑定课程上下文，使file_rewrite_pluginfile_urls()在内部被正确调用。
方案二：手动重写插件文件URL（适用于轻量集成）
若需最小侵入式修改，可显式调用 file_rewrite_pluginfile_urls()：
global $CFG;
require_once($CFG->libdir . '/filelib.php');
require_once($CFG->dirroot . '/course/lib.php');
$context = context_course::instance($course->id);
$summary = file_rewrite_pluginfile_urls(
$course->summary,
'pluginfile.php',
$context->id,
'course',
'summary',
null // itemid — summary 固定为 null
);
echo format_text($summary, $course->summaryformat, ['filter' => true]);⚠️ 注意事项：
- 必须确保 $course->id 有效且课程存在，否则 context_course::instance() 将抛出异常；
- file_rewrite_pluginfile_urls() 仅重写URL，不执行文本过滤，因此仍需配合 format_text() 启用富文本渲染与安全过滤；
- 避免硬编码路径，始终使用 $CFG->libdir 或 $CFG->dirroot 常量；
- 若摘要含视频、音频或嵌入iframe，需确认对应过滤器（如media, multilang）已在站点启用。
? 总结
根本原因在于Moodle的安全文件访问机制要求所有pluginfile.php链接必须绑定有效的上下文ID。直接输出原始$course->summary字符串会绕过上下文感知流程。始终通过format_text()传入'context'参数，或先调用file_rewrite_pluginfile_urls()再渲染，是确保摘要图片、附件及富媒体正常显示的唯一可靠方式。 开发中建议优先采用方案一，兼顾可维护性与Moodle最佳实践。
