league/commonmark安装失败主因是PHP版本低于7.4或缺失mbstring/json扩展；v2不支持PHP8.2+需改用^3.0；v3废弃MarkdownConverter类，改用Environment+MarkdownConverter构造并链式调用getContent()。
composer require league/commonmark 装不上？先看 PHP 版本和扩展
装不上 league/commonmark，八成不是命令写错，而是环境卡住了。它最低要求 PHP 7.4，且依赖 mbstring 和 json 扩展——这两个在某些精简版 Docker 镜像或旧服务器上默认不启用。
- 运行
php -v确认版本 ≥ 7.4；php -m | grep mbstring检查扩展是否加载 - 如果用的是 PHP 8.2+，注意
league/commonmark2.x 不支持，得切到 3.x：composer require league/commonmark:^3.0 - 若项目已锁死
symfony/console或psr/cache等依赖版本，Composer 会静默拒绝安装——加-vvv参数看真实冲突提示，别只盯着“nothing to install”
渲染 Markdown 时中文标题乱码或链接失效？检查解析器配置
CommonMark 默认按 CommonMark Spec 解析，但标准里不处理中文标点自动换行、全角括号链接识别等——这些不是 bug，是设计如此。直接用 Environment::createCommonMarkEnvironment() 渲染，大概率发现「# 中文标题」没转成 <h1>，或者 [文本](url) 里的中文路径被截断。
- 必须显式启用
HeadingPermalinkExtension（带锚点）或TableOfContentsExtension（目录）才能让标题可链接，它们不包含在基础环境里 - 中文 URL 需提前用
rawurlencode()处理，CommonMark 不自动编码；否则[点击](/文章/你好.md)会被当成无效链接丢弃 - 如需支持「==高亮==」或「:::warning」这类自定义容器，得手动注册
CustomBlockExtension，基础包不带
升级到 v3 后 MarkdownConverter 报错 Class not found？接口全变了
v3 彻底废弃了 MarkdownConverter 类，改用 MarkdownConverterInterface + Environment 构造，老代码直接崩。这不是兼容性补丁能绕过的，是架构重写。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- v2 写法：
$converter = new MarkdownConverter(); $html = $converter->convertToHtml($md); - v3 正确写法：
$environment = Environment::createCommonMarkEnvironment(); $converter = new MarkdownConverter($environment); $html = $converter->convert($md)->getContent(); - v3 的
convert()返回Document对象，必须链式调用getContent()才拿到字符串，漏掉就返回对象而非 HTML - 如果你还在用 Laravel，注意
league/commonmarkv3 不再提供League\CommonMark\Environment\Environment::createCommonMarkEnvironment()的静态快捷方法，得自己 new
性能差、页面卡顿？别让 CommonMark 在每次请求里重复构建 Environment
Environment 初始化开销不小，尤其加了多个扩展后。如果在控制器或模板里每次都 Environment::createCommonMarkEnvironment()，CPU 会明显升高，尤其并发稍高时。
- 必须把
Environment实例作为单例注入（如 Laravel 的 Service Container），或至少缓存在静态属性里 - 避免在循环里反复调用
convert()：先批量解析成Document，再统一渲染，比逐条convert($md)->getContent()快 3–5 倍 - 如只是渲染简单文档（无扩展、无自定义语法），用
new Environment()替代createCommonMarkEnvironment()可省掉一堆默认扩展加载
最常被忽略的一点：v3 的 Environment 不再自动合并扩展配置，addExtension() 调用顺序会影响解析结果——比如 StrikethroughExtension 必须在 SmartPunctExtension 之后注册，否则 ~~删除线~~ 里的波浪线会被当成智能标点吞掉。
