Laravel 中需先安装 league/commonmark 扩展才能使用 markdown() 辅助函数，否则报错；Blade 中须用 {!! markdown($content) !!} 渲染，避免转义；深度定制需手动配置 CommonMark 环境而非依赖默认函数。
怎么在 Laravel 里把 Markdown 字符串转成 HTML
直接用 markdown() 辅助函数最省事，但得先装扩展。Laravel 自身不带 Markdown 解析器，得靠 league/commonmark 这类第三方库打底。
常见错误是直接调 markdown() 却没装包，报错 Call to undefined function markdown() —— 这不是你写错了，是环境缺依赖。
- 运行
composer require league/commonmark（Laravel 9+ 原生支持，低版本需手动注册服务提供者） - 确保已启用
Illuminate\Support\ServiceProvider类（默认开启，一般不用动） -
markdown()只接受字符串，不能传File对象或路径；想解析文件内容，得先file_get_contents()或Storage::get() - 它默认禁用 HTML 标签（安全考虑），如果源 Markdown 里写了
<div> 之类，会被原样输出或过滤掉<p>示例：</p><pre class="brush:php;toolbar:false;">echo markdown('# Hello World'); // 输出 <h1>Hello World</h1></pre><h3>怎么让 Blade 模板里直接写 Markdown 内容块</h3> <p>Blade 不认识 <code>```或#，必须显式调用解析函数，不能像 Vue 的v-html那样自动处理。容易踩的坑是把 Markdown 当普通文本插进 Blade，结果页面上全是原始符号：「
## 章节标题」原样显示，而不是变成二级标题。- 别写
{{ $content }}—— 这会 HTML 转义，连 `` 都被当文本渲染
- 改用
{!! markdown($content) !!}，注意双大括号加感叹号，表示不转义 - 如果
$content来自用户输入，务必先过滤 XSS（commonmark默认已禁用 HTML，但自定义扩展可能绕过） - 避免在循环里反复调
markdown()，解析有开销；大批量内容建议提前缓存 HTML 版本
怎么自定义 Markdown 渲染效果（比如加 class、改 heading 标签）
默认
markdown()走的是基础配置，heading 渲染成<h2></h2>就完事，没法加id或class—— 这时候得换用CommonMarkConverter实例，手动控制。很多人试过改配置数组却没生效，是因为 Laravel 的
markdown()函数封装了一层，默认不读你传的选项。- 要深度定制，别用辅助函数，改用
League\CommonMark\Environment\Environment+HtmlRenderer - 比如给所有
h2加class="section-title"，得注册自定义HeadingRenderer - 配置项如
allow_unsafe_links、max_nesting_level影响解析深度和安全性，设太高可能引发栈溢出 - Laravel 10+ 开始支持通过
config/markdown.php文件统一配置，但需手动发布配置：运行php artisan vendor:publish --provider="Illuminate\Markdown\MarkdownServiceProvider"
为什么本地能渲染，上线后变空白或报错
大概率是生产环境没装扩展，或者 OPcache 缓存了旧的类映射，导致
CommonMarkConverter找不到。另一个隐蔽问题是 PHP 版本兼容性：
league/commonmark ^2.0要求 PHP >= 7.4，而有些老服务器还跑着 7.3，composer install表面成功，实际加载时报ParseError。- 上线前执行
composer show league/commonmark确认版本匹配 PHP 版本 - 清空 OPcache：
php artisan opcache:clear（如果启用了） - 检查日志里有没有
Class 'League\CommonMark\Environment\Environment' not found，这是典型的 autoloader 失效 - 别依赖
dev-master分支，生产环境固定用^2.4这类稳定版
Markdown 渲染看着简单，但环境差异、版本锁、HTML 安全边界这几个点，最容易在交接或部署时突然冒出来。
- 别写
