Umi 开源仓库贡献者完全指南从环境搭建、开发调试到文档贡献与发版流程【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi本篇指南以 Umi 仓库官方贡献文档为主体系统梳理参与 Umi 开发与维护的完整工作流从 Node.js/pnpm 环境准备、依赖安装与构建到本地开发调试、跑 Example 验证、测试执行再到基于 MDX 的文档贡献、新增 package、依赖更新以及基于 OIDC 的发布与回滚流程。读完本文你将掌握在本地以 monorepo 方式开发、验证和发布 Umi 各 package 的标准动作并能对照仓库源码理解每一步背后真实的执行逻辑。环境准备Node.js 18 与 pnpm v8开发 Umi 需要满足两项基础环境要求Node.js 18pnpm v8仓库根目录 package.json 中声明了packageManager: pnpm8.15.9且preinstall脚本使用only-allow pnpm强制使用 pnpm官方推荐使用Volta统一管理 Node.js 与 pnpm 版本。由于 Volta 默认不接管 pnpm需要先设置环境变量启用 pnpm 支持export VOLTA_FEATURE_PNPM1Volta 会在当前项目目录存在volta字段时自动切换到对应版本。仓库根目录 package.json 已声明volta.node与volta.pnpm因此volta install后即可获得团队一致的开发环境。Clone 项目并安装依赖、构建$ git clone gitgithub.com:umijs/umi.git $ cd umi进入仓库后一条命令完成依赖安装与全量构建$ pnpm i pnpm build其中pnpm i安装全部 workspace 依赖根目录 pnpm-workspace.yaml 定义了 monorepo 范围安装后postinstall会执行 scripts/postinstall.ts 做必要的初始化pnpm build实际调用umi-scripts turbo build即通过 Turborepo 编排各 package 的构建turbo.json中build任务依赖上游^build产物输出到各 package 的dist/**。开发 Umi启动 dev 编译本地开发 Umi 必开的命令是$ pnpm dev它的作用是编译src下的 TypeScript 源码到各 package 的dist目录并监听文件变更发生改动时增量编译。根目录 package.json 中dev脚本为umi-scripts turbo dev --parallel会并行启动所有 package 的编译任务turbo.json 中dev任务关闭了缓存保证改动即时生效。如果全量编译较慢可以只跑特定 package 的 dev例如$ cd packages/umi $ pnpm dev由于各 package 相互依赖如umi依赖umijs/core、umijs/preset-umi等建议先保证依赖方的dist已经构建过再单独开发目标 package。跑 Example 验证功能examples目录保存了各种用于测试的场景如boilerplate、with-antd、ssr-demo、qiankun-master等跑 example 是开发 Umi 时确认功能正常的最常用方式。每个 example 都配置了 dev 脚本直接进入目录执行即可$ cd examples/boilerplate $ pnpm dev如需使用vite 模式运行追加--vite参数$ pnpm dev --vite这与仓库同时内置 webpack/vite 双 bundler 的架构一致便于在两种模式间切换验证同一功能。测试pnpm test 与 pnpm jestUmi 的测试速度很快通常十几秒即可完成官方建议本地先跑一遍再提 PR以减少评审往返Round Trip。$ pnpm test ... Test Suites: 1 skipped, 43 passed, 43 of 44 total Tests: 6 skipped, 167 passed, 173 total Snapshots: 0 total Time: 13.658 s Ran all test suites.需要注意根目录 package.json 中test脚本即jest而各 package 内通过umi-scripts jest-turbo运行测试开启 Turborepo 任务编排因此全量跑测试用pnpm test只跑部分文件的用例用pnpm jest避免 Turbo 的全量调度开销。例如只运行文档插件的编译器测试$ pnpm jest packages/plugin-docs/src/compiler.test.ts对应源码 packages/plugin-docs/src/compiler.test.ts 与本仓库的 jest 配置jest.config.ts、jest.turbo.config.ts保持一致。仓库还提供pnpm test:e2e使用 jest.e2e.config.ts用于运行端到端用例。贡献 Umi 文档启动文档开发环境Umi 的文档由 Umi4 和umijs/plugin-docs插件实现本质上就是一个 Umi 项目。在根目录执行# 启用 Umi 文档开发 # 首次启动时编译耗时较长请耐心等待 $ pnpm docs:dev该命令实际为pnpm --filter umijs/docs dev见 package.json。启动后打开指定端口即可实时查看文档更新内容以及umijs/plugin-docs插件开发的成果。Umi 会监听docs和packages/plugin-docs/client目录下文件的变化。撰写文档基于 MDX 与组件Umi 文档基于MDX格式编写。MDX 是 Markdown 的扩展允许在文档中直接插入 JSX 组件撰写**文档Document**时可用组件位于 packages/plugin-docs/client/theme-doc/components如Features、FeatureItem、Hero、Message、Tabbed、Announcement等撰写**博客Blog**时可用组件位于 packages/plugin-docs/client/theme-blog/components。代码高亮基于Rehype Pretty Code实现完整能力以其官方文档为准。仓库侧的具体集成见 packages/plugin-docs/src/compiler.ts编译流程使用mdx-js/mdx的createProcessor依次接入remark-gfmGFM 表格/任务列表、rehype-slug标题锚点、rehype-pretty-code代码高亮主题为dark-plus并支持行高亮与词高亮的样式类注入与rehype-autolink-headings标题自动链接。格式化文档在根目录执行$ pnpm format:docs对应脚本为prettier --cache docs/**/*.{md,mdx} --write。格式化文档后建议仅提交你撰写或修改的文档——不同贡献者写作风格有差异格式化后不一定能保留原期望的样式。参与文档插件开发新建一个终端进入插件目录并启动 CSS 编译$ cd packages/plugin-docs $ pnpm dev:css该命令即tailwindcss -i ./client/theme-doc/tailwind.css -o ./client/theme-doc/tailwind.out.css --watch。此后修改 packages/plugin-docs/client/theme-doc/tailwind.css 或在开发时新增 TailwindCSS 样式类都会自动编译生成tailwind.out.css。需要特别注意的是Umi 只监听docs与packages/plugin-docs/client目录不会监听packages/plugin-docs/src。如果需要编译src中的文件应移动到packages/plugin-docs目录下执行pnpm build即umi-scripts father buildbuild:css然后重启开发。相关辅助命令# 格式化插件代码 $ pnpm format:plugin-docs # 构建 Umi 文档 $ pnpm s新增 package新增 package 有封装脚本无需手动复制package.json等文件# 创建 package 目录 $ mkdir packages/foo # 初始化 package 开发 $ pnpm bootstrappnpm bootstrap对应umi-scripts bootstrap实现见 scripts/bootstrap.ts。脚本会遍历packages目录为尚不存在package.json的目录自动生成一整套标准文件package.json自动生成包名umi保留原名其余前缀umijs/、同步 lerna 版本号读取根目录 lerna.json、main/types指向dist并写入build/build:deps/dev等标准 scriptsREADME.md、tsconfig.json继承根目录 tsconfig.base.json、.fatherrc.ts继承.fatherrc.base.ts使用 father 构建若src不存在还会生成一个默认的src/index.ts与其配套的src/index.test.ts冒烟测试。更新依赖不推荐非 Core Maintainer 做大量依赖更新。因为涉及依赖预打包有较多需注意的点。执行以下命令可交互式更新依赖$ pnpm dep:update对应脚本为pnpm up --interactive --latest --recursive。由于 Umi 对依赖做了**预打包bundle deps**处理更新依赖后还需检查更新的依赖是否为devDependencies以及是否已配置依赖预打包。如果是需要在对应 package 下执行build:deps并指定该依赖用于更新预打包文件$ pnpm build:deps --dep webpack-manifest-plugin预打包机制在packages/plugin-docs中可见一斑其package.json的compiledConfig.deps声明了mdx-js/mdx、rehype-slug、remark-gfm、rehype-autolink-headings等依赖构建后产物落在 packages/plugin-docs/compiled 目录供src直接引用。发布基于 OIDC 的自动化流程只有 Core Maintainer 才能执行发布。Umi 已切换到npm Trusted Publishing / OIDC本地发布命令只负责 bump version、生成 release commit/tag 并推送不再直接执行npm publish。$ pnpm release本地发布脚本见 scripts/release.ts执行一系列前置检查与步骤检查 git 分支、工作区是否干净、是否落后于远端校验 npm registry 为https://registry.npmjs.org/通过lerna changed确认有 package 变更并运行check:packageFiles校验各 package 文件清理并执行pnpm build:release构建lerna version统一 bump 版本--exact精确版本、不推 tag并依据版本号决定发布 tag-alpha./-beta./-rc.→next-canary.→canary否则latest更新examples下各 example 的 scripts、更新 lockfile、生成 release commit 与 git tagv${version}最后推送。推送后GitHub Actions 的 Release workflow 通过 OIDC 获取 npm 发布权限执行pnpm release:publish并带--provenance将 package 发布到 npm。对应脚本 scripts/releasePublish.ts 会按依赖顺序发布先发布除umi/max外的 packages再发布umi、max逐个执行pnpm pack、解包到临时目录后npm publish --tag tag --access public --provenance并跳过已发布版本。通过 dist-tag 回滚例如要回滚到4.0.81$ pnpm -rc --filter ./packages/** exec pnpm dist-tag add \$PNPM_PACKAGE_NAME4.0.81 latest该命令递归遍历packages下所有 package将latestdist-tag 指回旧版本实现快速回滚。加入 Contributor 群提交过 Bugfix 或 Feature 类 PR 的同学如果有兴趣一起参与维护 Umi可按文档说明用钉钉扫码注明 github id联系维护者加入 Contributor 群。如果你暂时不知道可以贡献什么可以到源码中搜索TODO或FIXME寻找可改进点例如在 packages、scripts 等目录下都有大量可挖掘的优化空间。小结贡献 Umi 的完整动作清单场景命令环境准备Node.js 18、pnpm v8Volta VOLTA_FEATURE_PNPM1安装并构建pnpm i pnpm build本地增量编译pnpm dev或进入单 package 执行验证功能进入examples/*后pnpm dev可加--vite全量测试pnpm test局部测试pnpm jest path文档开发pnpm docs:dev文档插件 CSScd packages/plugin-docs pnpm dev:css新增 packagemkdir packages/foo pnpm bootstrap更新依赖pnpm dep:updatepnpm build:deps --dep name发布Core Maintainerpnpm releaseCI 内pnpm release:publish回滚pnpm -rc --filter ./packages/** exec pnpm dist-tag add ...从克隆仓库到提交 PR再到维护者发版本文覆盖了 Umi 开源协作的完整链路。你可以对照 package.json 的 scripts 与 scripts 目录下的实现逐步实操在本地跑通属于自己的第一次贡献。【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考