Marp CLI 浏览器启动失败问题分析与解决方案

问题背景

Marp CLI 是一款基于 Node.js 的 Markdown 幻灯片转换工具，它能够将 Markdown 文件转换为各种格式的演示文稿。在实际使用中，特别是在 macOS 系统上，用户可能会遇到一个棘手的问题：当尝试同时运行多个 Marp CLI 进程进行 PDF 转换时，浏览器无法正常启动，导致转换失败。

问题现象

当用户执行以下操作序列时会出现问题：

1. 首先启动 Marp CLI 服务器模式
2. 通过浏览器访问某个 Markdown 文件并请求 PDF 转换
3. 同时尝试通过另一个 Marp CLI 进程（如 VS Code 的导出命令）进行 PDF 转换

此时第二个转换进程会失败，并显示错误信息，指出无法创建 SingletonLock 文件，因为该文件已存在。错误还提示 Chrome 无法为配置文件目录创建 ProcessSingleton，这意味着系统试图启动多个浏览器进程而不是在现有进程中打开新窗口。

技术原理分析

这个问题源于 Chrome/Chromium 浏览器对用户数据目录（userDataDir）的单例锁机制。Chrome 设计上要求同一用户数据目录只能被一个浏览器进程独占访问，这是通过创建名为 SingletonLock 的锁文件来实现的。

Marp CLI 目前使用了一个固定的临时目录作为 Chrome 的用户数据目录。当第一个转换进程启动时，它会创建这个目录和 SingletonLock 文件。当第二个转换进程尝试使用相同的用户数据目录时，由于锁文件已存在，Chrome 会拒绝启动，以防止多个进程同时访问同一用户数据目录可能导致的配置文件损坏。

解决方案

要解决这个问题，核心思路是确保每个 Marp CLI 转换进程使用唯一的用户数据目录。具体可以考虑以下几种实现方式：

1. 动态生成唯一目录名：为每次转换生成一个带有随机或唯一标识符（如时间戳+随机数）的临时目录，确保不同进程不会冲突。

2. 进程级隔离：在启动浏览器实例时，检查并确保用户数据目录是进程唯一的。

3. 清理机制：在转换完成后，及时清理临时创建的用户数据目录，避免积累大量无用目录。

实现建议

在实际实现中，推荐采用第一种方案，即在创建临时目录时加入唯一性保证。例如，可以使用 Node.js 的 os.tmpdir() 结合 uuid 或时间戳来生成唯一的目录路径：

const path = require('path')
const os = require('os')
const { v4: uuidv4 } = require('uuid')

const uniqueUserDataDir = path.join(os.tmpdir(), `marp-cli-conversion-${uuidv4()}`)

这样每个转换进程都会使用完全独立的用户数据目录，从根本上避免了单例锁冲突的问题。

注意事项

1. 资源清理：虽然现代操作系统会定期清理临时目录，但良好的实践是在转换完成后主动删除临时创建的用户数据目录。

2. 性能考量：创建新的用户数据目录会导致 Chrome 需要初始化新的配置文件，可能会略微增加启动时间，但相比转换失败的代价，这是可以接受的折衷。

3. 跨平台兼容性：解决方案需要在不同操作系统上都能正常工作，特别是路径分隔符等细节需要注意。

总结

Marp CLI 的浏览器启动失败问题本质上是由于 Chrome 的用户数据目录单例锁机制与固定临时目录方案的冲突。通过为每个转换进程分配唯一的用户数据目录，可以优雅地解决这个问题，同时保持系统的稳定性和可靠性。这种解决方案不仅适用于当前问题，也为未来可能的并行转换需求奠定了基础。