Milkdown 贡献者开发指南基于 pnpm 工作区的构建、测试与提交流程实战【免费下载链接】milkdown Plugin driven WYSIWYG markdown editor framework.项目地址: https://gitcode.com/GitHub_Trending/mi/milkdown本文以仓库根目录 CONTRIBUTING.md 为核心骨架面向想要参与 Milkdown 开源开发的贡献者完整讲解从环境准备、依赖安装、Storybook 本地调试到单元测试 / E2E 测试 / 代码规范 / 类型检查 / 构建与规范化提交的全流程。读完本文你将掌握 Milkdown 这套多包 monorepo 仓库的标准开发工作流知道每个常用命令背后的实际脚本与工具链并能在提交 Pull Request 前独立完成自检。Milkdown 是一个插件驱动的所见即所得WYSIWYGMarkdown 编辑器框架基于 ProseMirror 与 remark 构建整个仓库采用 pnpm workspace 组织的 monorepo 结构。本文所有命令与结论均以当前仓库真实配置为依据你可以一边阅读一边在本地仓库中执行验证。一、项目结构与开发工作流概览在动手之前先理解仓库的顶层布局。通过 pnpm-workspace.yaml 可以看到Milkdown 的 workspace 由以下几类成员组成packages/*核心包例如packages/core编辑器内核、packages/ctx上下文容器、packages/proseProseMirror 封装、packages/transformerMarkdown 与文档树转换等packages/plugins/*全部插件与预设如preset-commonmark、preset-gfm、plugin-history、plugin-listener、theme-nord等packages/integrations/*框架集成层如integrations/react、integrations/vuee2e基于 Playwright 的端到端测试工程storybookStorybook 组件调试站点dev与docs内部开发工具包与自动生成的 API 文档工程。顶层 tsconfig.json 通过 TypeScript Project References 把上述所有包串联起来每个包都有独立的tsconfig.json因此构建时按依赖图顺序编译。理解这一结构后再来走 CONTRIBUTING.md 定义的完整开发流程安装依赖 → 构建 → 启动 Storybook → 修改代码 → 跑测试与检查 → 提交 PR。二、开发环境准备Node.js、npm 与 corepack 启用 pnpmMilkdown 官方开发流程明确要求使用 corepack 配合 pnpm 进行开发且本机必须已安装 node.js 与 npm并确保 corepack 已启用原文引用自 CONTRIBUTING.md 开头的注释说明。这是整个开发工作流的起点。corepack 是 Node.js 自带的包管理器版本管理工具启用后它会读取仓库内声明的packageManager字段自动下载并使用对应版本的 pnpm避免团队成员各自安装不同版本导致的锁文件漂移问题。当前仓库在 package.json 中声明packageManager: pnpm11.20.0固定 pnpm 版本engines: { node: 22 }要求 Node.js 版本不低于 22。因此一个标准的环境检查顺序是确认node -v满足22确认npm -v可用执行corepack enable启用 corepack在仓库根目录执行pnpm installcorepack 会按packageManager字段自动切换并锁定 pnpm11.20.0。提示从 package.json 的prepare: husky脚本可以看出pnpm install完成后 husky 会自动初始化 git hooks见下文“Pre Check”部分所以首次安装依赖时请确保 git 仓库上下文完整。三、安装依赖并启动本地开发服务器根据 CONTRIBUTING.md 的 Development Workflow 章节克隆仓库后需要依次执行三条命令pnpm install # 安装全部 workspace 依赖 pnpm build # 构建所有包 pnpm start # 在另一个终端中启动 Storybook 调试站点其中pnpm install一次性安装packages/*、packages/plugins/*、packages/integrations/*、e2e、storybook、dev、docs各子工程的依赖。注意 pnpm-workspace.yaml 中还配置了peerDependencyRules如忽略 prosemirror-* 与 vue 等 peer 依赖缺失告警以及overrides将一批 polyfill 包重定向到nolyfill/*以统一版本这些配置保证了跨包依赖解析的一致性。pnpm build先做 TypeScript 类型检查与编译再逐个构建发布产物详见下文“构建系统解析”。pnpm start启动 Storybook。对应 storybook/package.json 中的start: storybook dev -p 6006即开发服务器默认监听6006端口。Milkdown 的全部核心能力Crepe 编辑器、各组件、主题都在storybook/stories下以 stories 的形式提供实时调试入口例如crepe/crepe.stories.ts、components/code-block.stories.ts、components/table-block.stories.ts等。四、命令参考构建、测试、清理与提交CONTRIBUTING.md 的 Commands 章节列举了贡献者最常使用的八条命令下表将其与当前仓库 package.json 中的真实脚本一一对应方便你在执行前了解其底层行为文档中的命令底层脚本package.json作用pnpm clearrimraf packages/*/{lib,tsconfig.tsbuildinfo,node_modules,.rollup.cache} rimraf node_modules删除所有包与根目录的构建产物lib、TypeScript 增量构建缓存tsconfig.tsbuildinfo、.rollup.cache与node_modules用于彻底清理环境pnpm test:unitvitest run运行所有包的单元测试配置见根目录 vitest.config.mts它会以packages/**/*/vitest.config.ts为项目入口聚合各包测试pnpm test:e2epnpm --filtermilkdown/e2e test运行 Playwright 端到端测试见 e2e/package.jsonpnpm test:e2e:debugpnpm --filtermilkdown/e2e run test:debug以 Playwright 的 UI 模式运行 E2E 测试便于逐步排查失败用例pnpm test:lintoxlint -c .oxlintrc.json --deny-warnings基于 oxlint 检查代码风格--deny-warnings表示把警告升级为错误任何告警都会导致检查失败pnpm test:tsc当前仓库未直接提供该脚本名最接近的是build:tsctsc -b tsconfig.json --verbose运行 TypeScript 类型检查。注意 CONTRIBUTING.md 中记载的脚本名与实际仓库略有出入实际类型检查/编译统一走pnpm build:tscpnpm buildpnpm build:tsc pnpm build:post后者为pnpm -r run build先对整个仓库做 TypeScript 编译再递归构建每个子包pnpm commitgit-cz启动 commitizen 风格的交互式提交向导结合 git hooks 生成规范化的提交信息除上述文档提及的命令外package.json 还提供几个值得了解的相关脚本pnpm test等价于pnpm test:lint pnpm test:unit即 PR 自检的完整命令见下文、pnpm test:unit:watchvitest 监听模式、pnpm changeset配合 changesets 生成版本变更集、pnpm codegen用 tsx 执行 scripts/gen-ts-config.mts 生成各包 tsconfig。五、构建系统解析从类型检查到产物打包pnpm build是提交流程中必须通过的一步理解它的两个阶段有助于定位构建失败阶段一pnpm build:tsc执行tsc -b tsconfig.json --verbose。-bbuild mode会按照 tsconfig.json 中声明的references顺序增量构建全部子项目——从dev、docs、e2e到 20 多个 packages 工程。由于启用了--verbose你可以清晰看到每个项目的编译过程tsconfig.tsbuildinfo缓存文件的存在也使得二次构建更快。阶段二pnpm build:post执行pnpm -r run build递归进入每个 workspace 包运行其各自的 build 脚本。以 packages/core/package.json 为例各包一般通过 Vite 或 Rollup如 packages/components/rollup.config.js、packages/prose/rollup.config.js产出lib目录下的分发文件。因此当你新增或修改了一个包时需要先让整个依赖链重新构建本地 Storybook 才能引用到最新代码——这正是 CONTRIBUTING.md 把pnpm build放在pnpm start之前的直接原因。六、测试体系单元测试与端到端测试Milkdown 的测试分为两层贡献者在改动涉及对应模块时必须确保两者通过6.1 单元测试pnpm test:unit根目录 vitest.config.mts 只做了一件事——把每个包下的vitest.config.ts作为独立 project 聚合进 vitest因此各包可以声明自己的测试环境与插件。仓库内的单测用例分布广泛例如packages/ctx/src/context/container.spec.ts 与 packages/ctx/src/timer/timer.spec.ts验证核心容器与计时器机制packages/crepe/src/default-config/default-config.spec.ts验证 Crepe 默认配置packages/crepe/src/llm-providers/providers.spec.ts验证 LLM Provider 抽象。单元测试适合验证编辑器内核、上下文容器、序列化器等与 DOM 无关或可 mock 的逻辑。6.2 端到端测试pnpm test:e2eE2E 部分在独立的e2eworkspace 中运行其 package.json 声明了 Playwright 相关脚本pnpm test:e2e # playwright test pnpm test:e2e:debug # playwright test --ui带 UI 的调试模式 pnpm test:install # playwright install --with-deps首次运行前安装浏览器测试工程通过 e2e/playwright.config.ts 配置用例按场景分目录组织e2e/tests/input输入行为如heading.spec.ts、bold.spec.ts、e2e/tests/transform文档转换、e2e/tests/crepeCrepe 完整功能如block-handle.spec.ts、table.spec.ts、e2e/tests/command、e2e/tests/shortcut等。每个场景目录下都有配套的 HTML/TS 入口如 e2e/src/preset-gfm/供 Vite 构建出测试页面后再由 Playwright 驱动真实浏览器验证。当你修改了某个插件或预设时通常需要在e2e/tests下补充或更新对应用例然后本地跑pnpm test:e2e:debug在 UI 模式下逐条观察执行结果。七、提交 PR 前的自检清单Pre CheckCONTRIBUTING.md 明确要求创建 Pull Request 之前必须完成以下自检Pre commit hooks 通过请不要忽略它。仓库通过 huskyprepare: husky脚本在pnpm install时安装 git hooks配合 commitlint.config.js继承commitlint/config-conventional与 .lintstagedrc.json 对暂存文件做提交信息规范校验与格式化检查。提交时若 hook 失败应修复而非--no-verify跳过。pnpm test通过。根据 package.jsonpnpm test等价于先跑pnpm test:lintoxlint 严格模式再跑pnpm test:unitvitest 全量单测。加上 PR 评审前的pnpm build就构成了“lint → unit → build”的完整本地门禁。作为补充建议涉及 E2E 场景的改动还应额外运行pnpm test:e2e并在提交信息上使用pnpm commitgit-cz 交互式向导以生成符合 Conventional Commits 规范的 message这也是后续 changesets 自动生成 CHANGELOG 的基础参见 scripts/changelog.mts。八、许可证与贡献约定CONTRIBUTING.md 最后声明向 Milkdown 贡献代码即表示你同意你的贡献以 MIT 许可证授权与仓库根目录 LICENSE 一致。这意味着你的补丁会与其他贡献者的代码一同以 MIT 协议对外分发提交前请确认你拥有所贡献代码的合法权利并接受这一授权条款。总结参与 Milkdown 开发的核心链路可以浓缩为五步corepack enable→pnpm install→pnpm build→pnpm startStorybook 调试→ 修改代码后依次通过pnpm test、pnpm test:e2e、pnpm build与 git hooks最后用pnpm commit提交并创建 PR。本文中的所有命令、脚本与测试路径都可以在当前仓库中直接核对遇到环境问题时可优先检查 Node 版本22与 pnpm 版本11.20.0是否与 package.json 声明一致。【免费下载链接】milkdown Plugin driven WYSIWYG markdown editor framework.项目地址: https://gitcode.com/GitHub_Trending/mi/milkdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考