应使用 composer require league/commonmark 安装 Markdown 解析器，而非 composer install 或错误包名；需引入 vendor/autoload.php 并按新版 API 创建 Environment 和 MarkdownConverter 实例；Web 环境输出 HTML 时须避免模板引擎自动转义。
composer install 时提示 “Package not found” 或 “Could not find package”
Composer 默认不支持直接安装 Markdown 解析器插件——因为 Markdown 解析不是 Composer 的职责，它只管 PHP 包的依赖管理。你搜到的“Markdown 插件”，实际是第三方 PHP 库，比如 league/commonmark 或 michelf/php-markdown，必须手动指定包名安装。
常见错误是输错包名，例如写成 composer install markdown（无效命令）或 composer require markdown（不存在这个包）。
- 正确做法：运行
composer require league/commonmark（推荐，语法规范、扩展性强） - 备选方案：用
composer require michelf/php-markdown（轻量，但不支持 CommonMark 标准） - 别写
composer install单独执行——它只读composer.lock，不拉新包；新增依赖必须用require
解析 .md 文件时抛出 “Class not found: League\CommonMark\Environment”
装完包不代表能直接用，PHP 自动加载机制没被触发，通常是因为没引入 autoloader，或用了旧版 API。
league/commonmark 2.x 起彻底弃用静态工厂方法，改用构建器模式，老教程里的 CommonMarkConverter::create() 会直接报错。
- 确保脚本开头有
require 'vendor/autoload.php'; - 新版写法：用
$environment = \League\CommonMark\Environment\Environment::createCommonMarkEnvironment();配合new \League\CommonMark\MarkdownConverter($environment) - 如果项目用了 Laravel 或 Symfony，autoloader 一般已自动加载，但依然要确认是否启用了 PSR-4 自动发现
解析结果里 HTML 标签被转义（显示为 <p> 而不是
）
这不是插件问题，而是你把解析后的 HTML 字符串当普通文本 echo/echo 出来了，框架或模板引擎做了二次转义。
典型场景：在 Twig 模板里写 {{ $html }}，默认开启 autoescape；在 Laravel Blade 里写 {{ $html }} 也会转义，而 {!! $html !!} 才原样输出。
- 检查输出上下文：CLI 脚本无此问题；Web 环境需确认模板引擎行为
- 不要试图用
htmlspecialchars_decode()补救——那是掩盖问题，不是修复逻辑 - 若需过滤 XSS，应使用专用库如
league/html-to-markdown反向处理，或集成HTMLPurifier
为什么用 league/commonmark 而不是 cebe/markdown？
两者都能解析 Markdown，但设计目标不同：cebe/markdown 更快、更轻，适合简单文档预览；league/commonmark 严格遵循 CommonMark 规范，支持扩展（如表格、脚注、自定义渲染器），适合需要稳定输出和未来兼容性的项目。
性能差异在千行以内文档几乎不可感，但一旦要加 GFM 表格或数学公式支持，cebe/markdown 就得自己 patch，而 league/commonmark 有现成扩展包 league/commonmark-ext-tables。
- 小项目快速上线：用
cebe/markdown没问题，composer require cebe/markdown后直接(new \cebe\markdown\Markdown())->parse($text) - 中大型项目或需长期维护：优先选
league/commonmark，尤其当你将来可能接入前端编辑器（如 Toast UI Editor）或导出 PDF - 别忽略 PHP 版本要求：
league/commonmark2.x 需 PHP 7.4+，低版本只能用 1.x（已 EOL）
最常被跳过的一步是检查 vendor/autoload.php 是否真的被引入——哪怕 composer install 成功了，漏掉这行，类就永远找不到。
