Cherry Markdown 贡献指南：Yarn workspace 与 Vite+ 驱动的开发、验证与 PR 全流程-开发者社区

前端
UI组件
富文本

【免费下载链接】cherry-markdown

✨ A Markdown Editor

项目地址：https://gitcode.com/GitHub_Trending/ch/cherry-markdown

Cherry Markdown 是一个以 Markdown 编辑器为核心的开源项目，仓库采用 Yarn workspace + Vite+（命令行简称vp）的统一工具链。本文以仓库根目录的 CONTRIBUTING.md 为主体，结合根目录 package.json、vite.config.ts、commitlint.config.js 与各子包配置，系统讲解从环境搭建、日常开发、修改验证到提交 PR 的完整贡献流程，让读者掌握一套可复现、与 CI 对齐的仓库级开发方法。

项目结构与工具链

贡献任何开源项目前，先建立正确的仓库整体认知。Cherry Markdown 的仓库结构与职责划分如下（以根目录CONTRIBUTING.md为准）：

packages/cherry-markdown：核心编辑器，产出 Full、Core、Stream、Engine 四类构建产物；
packages/miniProgram：小程序适配包；
packages/client：基于 Tauri 的桌面客户端；
packages/vscodePlugin：VS Code 插件；
examples/：示例与发布验证项目（其中examples/react_demo、examples/miniProgram同样被纳入 workspace）；
.changeset/：发布包的版本变更说明目录。

统一工具链是本文反复强调的第一原则。仓库是 Yarn workspace，项目使用 Vite+（命令行简称vp）统一处理依赖安装、workspace 任务编排、开发服务器、构建、测试和代码检查。根目录 package.json 的workspaces字段明确列出packages/*、examples/react_demo和examples/miniProgram；devDependencies中声明了vite-plus@0.2.6、vite@^8.2.1、vitest@4.1.10与typescript@^6.0.2。因此贡献者应当优先使用根目录脚本，不要在子包中引入另一套 workspace 工具或 lockfile。

开发环境准备

版本要求

根目录 package.json 的engines字段给出了硬性约束，与CONTRIBUTING.md完全一致：

Node.js：>=22，仓库根目录.node-version文件固定为24，推荐直接使用该版本，保证行为一致；
Yarn：1.22.18或更高；仓库通过packageManager字段固定为yarn@1.22.22+sha512.a6b2...，安装时会校验。
若开发桌面客户端，还需要 Rust 及 Tauri 系统依赖，具体见客户端贡献说明（该文件明确要求先安装 Rust 与 Node，并使用yarn install从仓库根目录安装依赖，禁止为该 workspace 单独引入 pnpm lockfile）；
若修改小程序示例，还需要微信开发者工具。

安装依赖

yarn install

安装完成后，根目录 package.json 的postinstall钩子会执行vp run -F cherry-markdown iconfont，为核心编辑器生成所需 iconfont 资源。若本机 shell 找不到vp，有两个备选入口：使用根目录脚本（例如yarn test），或直接调用./node_modules/.bin/vp——后续所有示例统一采用后者，这也是CONTRIBUTING.md推荐的做法。

日常开发工作流

分支策略

贡献流程从dev分支出发，每个 PR 保持聚焦单一主题：

git switch dev git pull --ff-only origin dev git switch -c feat/short-description

分支名建议使用feat/<简短描述>这类可读命名，避免把无关的历史提交合并进功能分支。

启动本地开发

启动核心编辑器示例：

yarn dev

根目录 package.json 中dev脚本实际执行vp dev --config packages/cherry-markdown/vite.config.ts，即通过 Vite 以核心包自身的 vite.config.ts 启动开发服务器，并运行vp run dev:core。

常用命令一览

以下命令表来自根目录 package.json，与CONTRIBUTING.md的命令表一一对应，均以vp为底层调度：

目的	命令
启动桌面客户端（Tauri）	`yarn dev:client`
启动 React 示例	`yarn example:react`
构建全部 workspace	`yarn build`
只构建核心包 / 小程序包	`yarn build:core`/`yarn build:miniProgram`
运行全部 / 核心 / 小程序测试	`yarn test`/`yarn test:core`/`yarn test:miniProgram`
类型检查	`yarn typecheck`
代码检查 / 自动修复	`yarn lint`/`yarn lint:fix`
更新测试快照	`yarn test:update`

各命令底层映射如下（见 package.json）：

yarn build依次构建核心包、小程序包、小程序示例、React 示例、客户端与 VS Code 插件；
yarn test仅运行核心包与小程序的测试；
yarn lint实际执行vp check，yarn lint:fix执行vp check --fix；
yarn typecheck依次对核心包与小程序执行类型检查。

针对单个 workspace 编排任务

使用 Vite+ 的过滤参数（-F）精准定位某个包：

./node_modules/.bin/vp run -F cherry-markdown build ./node_modules/.bin/vp run -F cherry-markdown test ./node_modules/.bin/vp run -F @cherry-markdown/miniprogram typecheck

注意包名差异：核心包过滤名是cherry-markdown，小程序包则是@cherry-markdown/miniprogram（与根目录package.json中 workspace 名称一致）。CONTRIBUTING.md特别强调：不要把vite、vitest或底层脚本当作根 workspace 的统一入口；它们应通过包脚本或vp调度，以确保本地行为与 CI 一致。根目录 vite.config.ts 中run.cache配置（scripts 关闭缓存、tasks 开启）也印证了vp承担任务编排与缓存职责。

修改与验证：一个可复现的流程

CONTRIBUTING.md给出了修改代码后的验证清单，下面是逐步展开：

先确认归属：判断修改属于哪个 package，阅读该 package 的 README、构建配置和现有测试。例如核心包源码位于 packages/cherry-markdown/src，测试位于 packages/cherry-markdown/test。
补测试：功能或缺陷修复应补充/更新对应测试；涉及编辑器行为时，同时在实际示例页面验证（核心包测试覆盖 hooks、toolbars、utils 等多个维度，如 HookCenter.spec.ts、BubbleFormula.spec.ts 等）。
写 changeset：涉及公开包、构建产物、依赖或发布行为时，在.changeset/新增变更说明；不要手工编辑生成的 changelog。仓库现有的.changeset/calm-images-rest.md给出了标准格式：frontmatter 声明受影响包'cherry-markdown': patch，正文一句话说明用户可见变化（如"销毁编辑器后忽略仍在进行的懒加载图片回调"）。
核心包改动完整验证：
```
yarn lint yarn typecheck yarn test yarn build
```
- yarn lint（即vp check）由根目录 vite.config.ts 统一调度 ESLint 检查；
- yarn typecheck在核心包内执行tsc --project tsconfig.json --noEmit与tsc --project test/tsconfig.json --noEmit（源码与测试两套配置都要过）；
- yarn build在核心包内串联clean → iconfont → build:styles → build:types → build:addons → build:full的完整流水线。
检查发布产物：
```
./node_modules/.bin/vp run -F cherry-markdown test:artifacts
```
该命令运行核心包 package.json 中的test:artifacts脚本，即vp test run test/build/built-artifact-contract.spec.js，覆盖 UMD、ESM、CSS、类型声明等公开产物。构建生成的dist不应作为源码修改提交，除非项目已有明确要求。
提交前检查：
```
git diff --check git status --short
```
根目录 vite.config.ts 中配置了 staged 检查：'*.{js,ts,tsx,vue,scss,css,json,md,mdx}': 'vp check --fix'，会在提交时自动处理暂存文件；提交钩子还会执行 commit message 校验。自动修复后请再次检查实际 diff，确认没有意外改动。

提交信息、Changeset 与 PR 规范

Conventional Commits 提交信息

提交信息遵循 Conventional Commits 规范，仓库通过根目录 commitlint.config.js 强制约束：

基于@commitlint/config-conventional；
type-enum限定类型枚举，包括feat、fix、docs、style、refactor、perf、test、chore、ci、build、revert、release、WIP；
自定义插件规则header-format通过正则/^[a-zA-Z]+(\([a-zA-Z0-9_-]+\))?:\s[^\s]/校验：冒号后面必须有且只有一个空格。

CONTRIBUTING.md中的示例：

fix(editor): preserve selection after paste feat(miniprogram): support streaming blocks docs: update contribution workflow

Changeset 写法

会进入发布包的改动，应在.changeset/<形容词-名词>.md中准确列出受影响的包和版本级别（patch/minor/major），并说明用户可见变化。纯文档、测试或内部 CI 改动通常不需要 changeset。仓库.changeset/目录中已有多个示例可供参考，例如calm-images-rest.md（patch）、four-onions-pay.md等，命名均为<形容词>-<名词>.md的随机风格。

PR 提交要点

PR 目标分支通常是dev；不要把无关的历史合并进功能分支；
PR 描述应说明背景、修改范围、验证命令及已知限制；
不要提交密钥、个人配置、构建缓存或未经确认的生成文件；
提交 PR 后等待 CI 完成，重点关注lint、typecheck、test、build和发布产物检查；
CI 使用 Vite+ 的vp install和vp run，本地应优先复现同一组根命令，从而保证本地验证与 CI 结果一致。

若只修改客户端、VS Code 插件或示例，请额外运行对应 workspace 的build、test或typecheck，并在 PR 中记录实际命令。例如客户端部分可参考 packages/client/CONTRIBUTING.md：yarn dev:client调用 Tauri 原生窗口与 Vite dev server（配置见 tauri.conf.json），yarn build:client构建客户端，打包原生产物使用./node_modules/.bin/vp run -F @cherry-markdown/client tauri:build。