企业官网建设流程全解析

Marp 生态大版本升级解读：Marpit v2、Marp Core v2 与 Marp CLI v1 的变更与迁移实践

【免费下载链接】marpThe entrance repository of Markdown presentation ecosystem项目地址: https://gitcode.com/gh_mirrors/mar/marp

2021 年 5 月，Marp 团队一次性发布了 Marp 生态的三个关键大版本——Marpit 框架 v2、Marp Core v2 以及 Marp CLI v1，本文基于 marp 仓库的官方发布公告 marpit-v2-marp-core-v2-and-marp-cli-v1.md，系统梳理这三个版本各自包含的破坏性变更、新增能力与底层依赖调整，并结合仓库文档给出升级与迁移的具体操作建议。读完本文，你将清楚知道这次大版本升级"改了什么、为什么改、影响谁、如何平滑迁移"，以及后续 Marpit v3 的演进方向。

一、为什么这次会同时发布三个大版本

要理解这次升级，先要明确 Marp 生态三个组件的分层关系。根据 README.md 与 whats-marp.md 的说明：

• Marpit：最底层的"瘦"框架，负责把 Markdown 转成幻灯片 HTML/CSS 的核心机制；
• Marp Core：在 Marpit 之上提供实用语法、内置主题（Default、Gaia、Uncover 等）与开箱即用能力的"完整版"转换器；
• Marp CLI：把 Marp Core / Marpit 封装成命令行接口，用于转换为 HTML、PDF、PPTX 和图片，是服务端转换与批处理场景的主力工具。

官方公告明确指出：这次升级之所以全部提升大版本号，核心原因只有一个——Node.js 10 已经到达生命周期终点（End-of-Life）。Marpit 与 Marp Core 在 Node 10 上依然可以运行，团队只是给出一个过渡窗口；但由于安全考量，官方不建议继续使用已过期的 Node.js 版本。这也是理解本次所有破坏性变更的主线。

二、Marpit v2.0.0：框架层的现代化改造

Marpit v2.0.0 是本次升级中位于最底层的改动，其变更直接影响所有基于 Marpit 构建的上层工具（包括 Marp Core 与 Marp CLI）。

破坏性变更：安装要求 Node.js >= 10

• Breaking：Marpit 从 v2.0.0 起要求 Node.js >= 10 才能安装。这是对 Node 10 寿命到期的直接响应，属于最低限度的版本约束调整。

内部依赖升级：PostCSS 8

• Changed：Marpit 将 CSS 处理核心从旧版 PostCSS 升级到PostCSS 8。这是一次底层构建链的现代化，影响面主要在主题 CSS 的解析与转换环节。对于大多数只写 Markdown、不深入框架内部的用户而言，该变化是透明的。
• Changed：同步升级 Node 版本要求与全部依赖包至最新版本。

移除已废弃接口：markdownItPlugins

• Removed：移除了markdownItPlugins——它是面向 markdown-it 插件体系的旧版 getter 接口。
• 影响面：如果你是基于 Marpit 的插件开发者，需要检查自己的插件是否依赖该 getter，并迁移到 Marpit 推荐的插件注册方式。普通幻灯片作者不受影响。

缺陷修复：高级背景中的 CSS columns

• Fixed：修复了高级背景（advanced background）场景下 CSScolumns属性未重置的问题，避免背景元素在特定渲染环境下出现意外的多栏布局。

三、Marp Core v2.0.0：主题定制能力的增强

Marp Core v2.0.0 的重点是主题层的定制能力升级，同时对底层框架进行了同步更新。

新增：Gaia 与 Uncover 主题支持 CSS 变量自定义颜色

本次版本最值得关注的新特性，是Gaia与Uncover内置主题开放了通过 CSS 变量（Custom Properties）自定义颜色的能力：

• Added：允许在 Gaia 和 Uncover 主题中通过 CSS 变量定制配色。

这意味着主题作者或幻灯片作者不再需要复制整套主题 CSS 来改颜色，而可以在 Marp 文档的<style>中声明:root级别的 CSS 变量，对主题颜色进行局部覆盖。典型的使用方式如下（变量名以你所使用的主题实际定义为准）：

<style> :root { /* 用 CSS 变量覆盖 Gaia / Uncover 主题中的颜色定义 */ --color-foreground: #0f4c81; --color-background: #f7f7f7; } </style>

结合 whats-marp.md 中"内容与样式分离（Separation of content and presentation）"的设计理念可以看出，CSS 变量方案正是这一理念的延伸：颜色这种高频定制点被提升为可配置的变量，用户无需改动主题源码即可换肤。

注意：官方同时提示，如果你的现有幻灯片带有自定义样式，覆盖变量后可能改变已有演示文稿的外观。这是本次升级中唯一明确提示"外观可能变化"的变更点，主题定制较深的用户升级后应回归检查。

依赖同步：升级到 Marpit v2.0.0

• Changed：Marp Core v2 将底层框架升级到 Marpit v2.0.0，从而继承上节所述的全部框架层改进（PostCSS 8、Node 要求等）。
• Changed：Node LTS 与全部依赖包同步升级至最新版本。

四、Marp CLI v1.0.0：迈向稳定的命令行工具

Marp CLI v1.0.0 是本次公告中最具里程碑意义的一个版本——官方明确表示"Marp CLI 正在走向稳定"。它不再只是实验性转换工具，而是覆盖 Docker、多平台 CI 场景的成熟 CLI。

破坏性变更：正式放弃 Node 10

• Breaking：Marp CLI v1 彻底移除了对 Node.js 10 的支持。配合 install.md 的说明，当前推荐使用 Node.js >= 12 的环境（如通过npx即装即用），更稳妥的做法是使用长期支持（LTS）版本的 Node.js。

新增：ARM64 Docker 容器镜像

• Added：构建并发布ARM64 架构的 Docker 容器镜像。此前 Docker 镜像主要面向 x86_64，ARM64 镜像的加入使 Marp CLI 可以原生运行在 Apple Silicon Mac、ARM 云服务器与树莓派等设备上，不再依赖模拟层。

新增：MARP_USER环境变量

• Added：Docker 镜像支持通过MARP_USER环境变量显式设置容器内运行进程的 UID/GID。这解决了容器内文件权限与宿主机不一致的常见痛点，便于在 CI 或挂载卷场景下正确读写文件。典型用法是在docker run时传入该变量：

# 将容器内进程的 UID/GID 显式指定为宿主机当前用户 docker run --rm -e MARP_USER="$(id -u):$(id -g)" \ -v "$PWD":/home/marp/app \ marpteam/marp-cli deck.md --pdf

容器镜像名为marpteam/marp-cli，此信息来自 install.md 中关于官方容器的说明。

新增：Windows 上的 Node 16 测试

• Added：在 Windows 平台上针对 Node.js 16 增加自动化测试，弥补此前平台/版本组合的覆盖缺口，提升跨平台可靠性。

依赖同步：内置 Marpit v2 与 Marp Core v2

• Changed：Marp CLI v1 内置了 Marpit v2.0.0 与 Marp Core v2.0.0，因此上面两节提到的所有框架层与核心层变更，都会随 Marp CLI 一起生效。
• Changed：Node 与全部依赖包升级至最新版本。

安装与使用方式

Marp CLI 提供了多种安装途径，完整说明见 install.md：

# 方式一：npx 即用即走（需要 Node.js >= 12），无需本地安装 npx @marp-team/marp-cli@latest markdown.md # 方式二：作为 Node 项目开发依赖安装 npm install --save-dev @marp-team/marp-cli npx marp markdown.md

也可以使用yarn add --dev @marp-team/marp-cli，或通过 Homebrew（macOS 的brew install marp-cli）、Scoop（Windows 的scoop install marp）以及独立二进制、Docker 镜像等方式安装。需要注意，官方不推荐全局安装marp命令。

如上图所示，Marp CLI 的核心工作流即"一条命令完成转换"：marp deck.md生成 HTML，marp deck.md --pdf生成 PDF，终端内会输出转换进度与产物路径。这也解释了为什么 Marp CLI 特别适合批处理、CI、服务端转换以及与其他工具通过管道组合的场景（详见 install.md 中 Marp CLI 适用场景清单）。

五、升级影响评估：谁需要关注这些变化

综合三个版本，本次升级的影响可以按下表快速定位：

值得一提的是，官方公告反复强调：尽管是大版本升级，但团队没有引入任何剧烈（drastic）变化，核心诉求是在不破坏现有幻灯片的前提下推进现代化。这与 the-story-of-marp-next.md 中"保持与普通 Markdown 文档的兼容性"的长期设计原则一脉相承。

六、未来路线：Marpit v3 的规划

公告在 "What's Next" 部分披露了 Marpit v3 的早期规划（官方同时坦承，由于维护精力有限，re-creation-of-marp-website.md 中预告的部分计划有所延期）：

• TypeScript 全量重写：Marpit v3 将使用 TypeScript 完整重写，提升类型安全与可维护性；
• 插件体系内部化：计划在内部把 Marp 幻灯片专属插件与框架核心分离，以便更好地与其他幻灯片渲染器协作；
• 异步转换支持：render()方法将支持返回 Promise，从而支持异步转换流程；
• 保留 Markdown 解析器：团队曾认真考虑更换 Markdown 解析器，但最终决定不换——因为大量 Marp 用户依赖第三方插件（markdown-it 生态），更换解析器会造成大面积破坏。

这一规划同样体现了 Marp 生态"最小化 + 兼容性优先"的长期路线。从后续发布的 202205-ecosystem-update.md 也可以看到，Marp 生态此后继续演进到 Marp Core v3 与 Marp CLI v2，本文所述的 v2/v1 版本为后续发展奠定了稳定的框架与工具链基础。

七、总结

Marpit v2、Marp Core v2 与 Marp CLI v1 的同期发布，标志着 Marp 生态在 2021 年完成了一次"低调但关键"的现代化：以 Node.js 10 终止支持为契机，完成了 PostCSS 8 升级、依赖整体更新、废弃接口清理（Marpit），开放了 Gaia / Uncover 主题的 CSS 变量配色能力（Marp Core），并让 Marp CLI 走向稳定——补齐 ARM64 镜像、MARP_USER权限控制与 Windows Node 16 测试矩阵。对于绝大多数用户，升级只需两步：把 Node.js 升级到受支持的版本，然后更新依赖到最新版；只有主题定制较深或基于框架开发插件的用户，才需要针对性地回归验证。如果你想在升级后动手验证，可以在当前仓库的 install.md 中查阅完整安装方式，用一份现有幻灯片快速做一次"升级前后渲染对比"。

【免费下载链接】marpThe entrance repository of Markdown presentation ecosystem项目地址: https://gitcode.com/gh_mirrors/mar/marp