尧图网站建设 
umi 贡献者指南从环境搭建到源码开发与发布的完整实践【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi本篇技术指南以 umi 官方 Contributing 文档为核心系统讲解在 umi 仓库中进行本地环境搭建、源码开发、文档维护、依赖更新与版本发布的完整流程。读完本文你将掌握 umi 从 clone 到提交 PR 再到理解其发布机制的全链路实操能力包括pnpm dev增量编译、examples 示例调试、umijs/plugin-docs文档体系、pnpm bootstrap新包初始化以及基于 OIDC 的 npm 发布流程。环境搭建Node.js 与 pnpm 版本要求开发 umi 要求Node.js 18和pnpm v8。推荐使用 Volta 管理 Node 与 pnpm 版本并需要设置VOLTA_FEATURE_PNPM环境变量以启用 pnpm 支持export VOLTA_FEATURE_PNPM1从仓库的根 package.json 可以看到版本约束的实际情况packageManager声明为pnpm8.15.9engines声明node 14、pnpm ^8.15.9同时volta字段固定了node 20.19.6与pnpm 8.15.9。也就是说根工程的 engines 声明略宽松而 Volta 固定版本与文档要求的 Node 18 / pnpm v8 保持一致实际开发时建议以仓库的 volta 配置为准。另外仓库通过preinstall脚本npx only-allow pnpm强制使用 pnpm 包管理器用 npm 或 yarn 安装会直接报错。克隆项目$ git clone gitgithub.com:umijs/umi.git $ cd umi安装依赖与构建$ pnpm i pnpm buildpnpm i会触发postinstallumi-scripts postinstall完成依赖预打包等初始化工作pnpm build在根目录实际执行的是umi-scripts turbo build通过 turbo.json 中build任务的dependsOn: [^build]保证先构建依赖包再构建自身并把dist/**作为缓存产物输出。开发 umi 本体启动 dev 命令pnpm dev是本地开发 umi 的必跑命令负责把各包src目录下的 TypeScript 源码编译到对应的dist目录并在文件变化时增量编译。根目录的 package.json 中该命令定义为umi-scripts turbo dev --parallel即并行监听所有包。如果觉得整体编译较慢可以只对单个包执行pnpm dev例如$ cd packages/umi $ pnpm devpackages/umi是 umi 的聚合出口包含 CLI 与 API 入口是最常单独调试的包之一其他包如umijs/core、umijs/preset-umi等同样可以单独进入目录执行pnpm dev。运行示例验证功能examples目录下包含大量用于测试的示例工程。运行示例是开发 umi 过程中验证功能是否正常的常用手段——每个示例都内置了 dev 脚本进入示例目录执行pnpm dev即可$ cd examples/boilerplate $ pnpm dev以 examples/boilerplate/package.json 为例其dev脚本为umi dev直接使用工作区内的umi包umi: workspace:*这意味着你修改packages/umi等包的源码并编译后重新启动示例即可拿到最新实现。若要以 vite 模式运行追加--vite参数$ pnpm dev --vite测试当前仓库的测试运行速度较快约 10 秒多完成官方建议在提交 PR 前先在本地跑一遍测试以减少来回沟通Round Trips。典型的输出如下$ 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.根目录pnpm test实际执行的是 jest见 package.json 中test: jest默认配置在 jest.config.ts 中其testMatch指向rootDir/packages/*/src/**/*.test.ts即各包 src 下的单元测试而pnpm test:e2ejest --config jest.e2e.config.ts用于端到端测试。如果只想跑特定文件请使用pnpm jest因为pnpm test在 turborepo 模式下运行。例如$ pnpm jest packages/plugin-docs/src/compiler.test.ts参与 umi 文档贡献文档是如何实现的umi 的文档由 umi4 本身与umijs/plugin-docs插件实现本质上就是一个 umi 工程。在根目录执行以下命令即可启动文档开发首次启动编译较慢请耐心等待$ pnpm docs:dev从根 package.json 可见docs:dev实际为pnpm --filter umijs/docs dev即运行docs目录下那个以umijs/plugin-docs驱动的文档工程。打开指定端口即可实时看到文档更新以及umijs/plugin-docs插件的开发效果。编写 umi 文档umi 文档采用MDX 格式编写。MDX 是 Markdown 的扩展允许在文档中直接插入 JSX 组件。:::success{title︎} 编写文档时可在packages/plugin-docs/client/theme-doc/components中查找可用组件编写博客文章时可用组件位于packages/plugin-docs/client/theme-blog/components。 :::以 packages/plugin-docs/client/theme-doc/components 为例仓库中提供了Announcement.tsx、FeatureItem.tsx、Features.tsx、Hero.tsx、Message.tsx、Tabbed.tsx等开箱即用的文档组件用于构建首页 Hero、特性列表、提示信息与标签页等常见板块。从 packages/plugin-docs/package.json 可以看到文档代码高亮基于rehype-pretty-code配合shikiMarkdown 解析与增强还依赖mdx-js/mdx、remark-gfm、rehype-slug、rehype-autolink-headings等编译期依赖这些依赖同时被声明在compiledConfig.deps中用于预打包。在根目录执行以下命令格式化现有 umi 文档$ pnpm format:docs该命令在 package.json 中定义为prettier --cache docs/**/*.{md,mdx} --write --ignore-path .gitignore --ignore-unknown即用 Prettier 统一格式化docs目录下的 Markdown/MDX 文件。格式化后建议只提交你自己编写或修改过的 umi 文档——不同文档贡献者写作风格各异格式化不一定能保留原作者想要的风格。参与文档插件开发新开一个终端执行以下命令$ cd packages/plugin-docs $ pnpm dev:css此后当你开发时修改tailwind.css文件或 TailwindCSS 样式类会自动编译生成tailwind.out.css样式表。从 packages/plugin-docs/package.json 的脚本定义可看到dev:css即pnpm build:css --watch而build:css为tailwindcss -i ./client/theme-doc/tailwind.css -o ./client/theme-doc/tailwind.out.css它基于 tailwind.config.js 将主题样式编译为最终的tailwind.out.css。umi 会监听docs与packages/plugin-docs/client目录的变化但不监听packages/plugin-docs/src的变化。:::info{title} 如果需要编译packages/plugin-docs/src下的文件请进入packages/plugin-docs目录执行pnpm build然后重启文档开发。 :::在根目录执行以下命令格式化文档插件的代码$ pnpm format:plugin-docs该命令为prettier --cache packages/plugin-docs/**/* --write --ignore-unknown。构建 umi 文档则执行$ pnpm docs:build即pnpm --filter umijs/docs build产出可用于静态部署的文档站点。新增一个包新增包已有封装好的脚本无需手动复制package.json等文件# 创建包目录 $ mkdir packages/foo # 初始化包开发 $ pnpm bootstrap根目录pnpm bootstrap执行的是umi-scripts bootstrap实现在 scripts/bootstrap.ts。从该脚本源码可以看出其工作原理遍历packages目录下每个子目录若不存在package.json则自动生成一套完整的包骨架包括package.json包名按规则生成umi保持原名其余为umijs/pkg版本取自lerna.jsonmain/types指向dist/index.js与dist/index.d.tsfiles仅发布dist并内置build/build:deps/dev脚本README.md、tsconfig.json继承根 tsconfig.base.jsonoutDir指向dist、rootDir指向src、.fatherrc.ts继承根.fatherrc.base.tssrc/index.ts 与 src/index.test.ts若src不存在则创建并写入一个返回包名的默认实现与对应单元测试。若目录已存在package.json脚本会保留已有字段authors、bin、files、scripts、dependencies等并合并默认值还可通过--force强制重新初始化。更新依赖不建议非 Core Maintainer 大批量更新依赖因为 umi 涉及依赖预打包需要注意的点很多。执行pnpm dep:update更新依赖即pnpm up --interactive --latest --recursive交互式选择升级到最新版本。由于 umi 会预打包部分依赖更新依赖后需要检查更新的依赖是否在 devDependencies 中、是否已被预打包。如果是则在对应包中执行pnpm build:deps并指定要更新的预打包依赖文件$ pnpm build:deps --dep webpack-manifest-pluginbuild:deps在包级脚本中对应umi-scripts bundleDeps实现见 scripts/bundleDeps.ts它依据各包package.json中compiledConfig声明的依赖清单重新生成compiled目录下的预打包文件如umijs/plugin-docs就在compiledConfig.deps中声明了mdx-js/mdx、rehype-slug、remark-gfm、rehype-autolink-headings等需要打进compiled目录的依赖。发布只有 Core Maintainer 才能执行发布。umi 目前已改用npm Trusted Publishing / OIDC因此本地发布命令只负责提升版本号、创建并推送 release commit/tag不再在本地执行npm publish$ pnpm releasepnpm release对应 scripts/release.ts其执行流水线依次为检查 git 状态干净、检查远端无落后、检查 npm registry 必须是官方源https://registry.npmjs.org/、通过lerna changed校验有变更的包、运行npm run check:packageFiles、清理各包dist、执行npm run build:release构建产物、用lerna version提升版本并生成latest/next/canary三种 npm tag根据版本号中是否包含-alpha./-beta./-rc.或-canary.、同步 examples 的 start 脚本、更新 pnpm lockfile最后提交release: versioncommit 并打 tag 推送到远端。推送之后GitHub Actions 的 Release workflow 通过 OIDC 获取 npm 发布权限运行pnpm release:publish即 scripts/releasePublish.ts将各包依次发布到 npm 并携带--provenance参数。该脚本会先通过npm view检查版本是否已发布已发布则跳过再在临时目录用pnpm pack打包、解包后执行npm publish --tag tag --access public --provenance同时支持--dry-run试跑发布顺序上先发布除umi/max外的依赖包最后发布umi与max两个聚合包。通过 dist-tag 回滚例如要回滚到 4.0.81$ pnpm -rc --filter ./packages/** exec pnpm dist-tag add \$PNPM_PACKAGE_NAME4.0.81 latest该命令对packages下所有子包递归执行pnpm dist-tag add把对应包的latestdist-tag 指回旧版本号从而实现不重新发版即可把默认安装版本回退。加入贡献者群凡提交过 Bugfix 或 Feature 类型 PR 且有兴趣参与 umi 维护的开发者可先用钉钉扫描官方文档中的二维码备注你的 GitHub id维护者会把你拉入贡献者群。如果你暂时不知道可以贡献什么可以在源码中搜索TODO或FIXME标记从这些待办点入手开始你的第一个 PR。【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 umi 贡献者指南：从环境搭建到源码开发与发布的完整实践
umi 贡献者指南从环境搭建到源码开发与发布的完整实践【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi本篇技术指南以 umi 官方 Contributing 文档为核心系统讲解在 umi 仓库中进行本地环境搭建、源码开发、文档维护、依赖更新与版本发布的完整流程。读完本文你将掌握 umi 从 clone 到提交 PR 再到理解其发布机制的全链路实操能力包括pnpm dev增量编译、examples 示例调试、umijs/plugin-docs文档体系、pnpm bootstrap新包初始化以及基于 OIDC 的 npm 发布流程。环境搭建Node.js 与 pnpm 版本要求开发 umi 要求Node.js 18和pnpm v8。推荐使用 Volta 管理 Node 与 pnpm 版本并需要设置VOLTA_FEATURE_PNPM环境变量以启用 pnpm 支持export VOLTA_FEATURE_PNPM1从仓库的根 package.json 可以看到版本约束的实际情况packageManager声明为pnpm8.15.9engines声明node 14、pnpm ^8.15.9同时volta字段固定了node 20.19.6与pnpm 8.15.9。也就是说根工程的 engines 声明略宽松而 Volta 固定版本与文档要求的 Node 18 / pnpm v8 保持一致实际开发时建议以仓库的 volta 配置为准。另外仓库通过preinstall脚本npx only-allow pnpm强制使用 pnpm 包管理器用 npm 或 yarn 安装会直接报错。克隆项目$ git clone gitgithub.com:umijs/umi.git $ cd umi安装依赖与构建$ pnpm i pnpm buildpnpm i会触发postinstallumi-scripts postinstall完成依赖预打包等初始化工作pnpm build在根目录实际执行的是umi-scripts turbo build通过 turbo.json 中build任务的dependsOn: [^build]保证先构建依赖包再构建自身并把dist/**作为缓存产物输出。开发 umi 本体启动 dev 命令pnpm dev是本地开发 umi 的必跑命令负责把各包src目录下的 TypeScript 源码编译到对应的dist目录并在文件变化时增量编译。根目录的 package.json 中该命令定义为umi-scripts turbo dev --parallel即并行监听所有包。如果觉得整体编译较慢可以只对单个包执行pnpm dev例如$ cd packages/umi $ pnpm devpackages/umi是 umi 的聚合出口包含 CLI 与 API 入口是最常单独调试的包之一其他包如umijs/core、umijs/preset-umi等同样可以单独进入目录执行pnpm dev。运行示例验证功能examples目录下包含大量用于测试的示例工程。运行示例是开发 umi 过程中验证功能是否正常的常用手段——每个示例都内置了 dev 脚本进入示例目录执行pnpm dev即可$ cd examples/boilerplate $ pnpm dev以 examples/boilerplate/package.json 为例其dev脚本为umi dev直接使用工作区内的umi包umi: workspace:*这意味着你修改packages/umi等包的源码并编译后重新启动示例即可拿到最新实现。若要以 vite 模式运行追加--vite参数$ pnpm dev --vite测试当前仓库的测试运行速度较快约 10 秒多完成官方建议在提交 PR 前先在本地跑一遍测试以减少来回沟通Round Trips。典型的输出如下$ 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.根目录pnpm test实际执行的是 jest见 package.json 中test: jest默认配置在 jest.config.ts 中其testMatch指向rootDir/packages/*/src/**/*.test.ts即各包 src 下的单元测试而pnpm test:e2ejest --config jest.e2e.config.ts用于端到端测试。如果只想跑特定文件请使用pnpm jest因为pnpm test在 turborepo 模式下运行。例如$ pnpm jest packages/plugin-docs/src/compiler.test.ts参与 umi 文档贡献文档是如何实现的umi 的文档由 umi4 本身与umijs/plugin-docs插件实现本质上就是一个 umi 工程。在根目录执行以下命令即可启动文档开发首次启动编译较慢请耐心等待$ pnpm docs:dev从根 package.json 可见docs:dev实际为pnpm --filter umijs/docs dev即运行docs目录下那个以umijs/plugin-docs驱动的文档工程。打开指定端口即可实时看到文档更新以及umijs/plugin-docs插件的开发效果。编写 umi 文档umi 文档采用MDX 格式编写。MDX 是 Markdown 的扩展允许在文档中直接插入 JSX 组件。:::success{title︎} 编写文档时可在packages/plugin-docs/client/theme-doc/components中查找可用组件编写博客文章时可用组件位于packages/plugin-docs/client/theme-blog/components。 :::以 packages/plugin-docs/client/theme-doc/components 为例仓库中提供了Announcement.tsx、FeatureItem.tsx、Features.tsx、Hero.tsx、Message.tsx、Tabbed.tsx等开箱即用的文档组件用于构建首页 Hero、特性列表、提示信息与标签页等常见板块。从 packages/plugin-docs/package.json 可以看到文档代码高亮基于rehype-pretty-code配合shikiMarkdown 解析与增强还依赖mdx-js/mdx、remark-gfm、rehype-slug、rehype-autolink-headings等编译期依赖这些依赖同时被声明在compiledConfig.deps中用于预打包。在根目录执行以下命令格式化现有 umi 文档$ pnpm format:docs该命令在 package.json 中定义为prettier --cache docs/**/*.{md,mdx} --write --ignore-path .gitignore --ignore-unknown即用 Prettier 统一格式化docs目录下的 Markdown/MDX 文件。格式化后建议只提交你自己编写或修改过的 umi 文档——不同文档贡献者写作风格各异格式化不一定能保留原作者想要的风格。参与文档插件开发新开一个终端执行以下命令$ cd packages/plugin-docs $ pnpm dev:css此后当你开发时修改tailwind.css文件或 TailwindCSS 样式类会自动编译生成tailwind.out.css样式表。从 packages/plugin-docs/package.json 的脚本定义可看到dev:css即pnpm build:css --watch而build:css为tailwindcss -i ./client/theme-doc/tailwind.css -o ./client/theme-doc/tailwind.out.css它基于 tailwind.config.js 将主题样式编译为最终的tailwind.out.css。umi 会监听docs与packages/plugin-docs/client目录的变化但不监听packages/plugin-docs/src的变化。:::info{title} 如果需要编译packages/plugin-docs/src下的文件请进入packages/plugin-docs目录执行pnpm build然后重启文档开发。 :::在根目录执行以下命令格式化文档插件的代码$ pnpm format:plugin-docs该命令为prettier --cache packages/plugin-docs/**/* --write --ignore-unknown。构建 umi 文档则执行$ pnpm docs:build即pnpm --filter umijs/docs build产出可用于静态部署的文档站点。新增一个包新增包已有封装好的脚本无需手动复制package.json等文件# 创建包目录 $ mkdir packages/foo # 初始化包开发 $ pnpm bootstrap根目录pnpm bootstrap执行的是umi-scripts bootstrap实现在 scripts/bootstrap.ts。从该脚本源码可以看出其工作原理遍历packages目录下每个子目录若不存在package.json则自动生成一套完整的包骨架包括package.json包名按规则生成umi保持原名其余为umijs/pkg版本取自lerna.jsonmain/types指向dist/index.js与dist/index.d.tsfiles仅发布dist并内置build/build:deps/dev脚本README.md、tsconfig.json继承根 tsconfig.base.jsonoutDir指向dist、rootDir指向src、.fatherrc.ts继承根.fatherrc.base.tssrc/index.ts 与 src/index.test.ts若src不存在则创建并写入一个返回包名的默认实现与对应单元测试。若目录已存在package.json脚本会保留已有字段authors、bin、files、scripts、dependencies等并合并默认值还可通过--force强制重新初始化。更新依赖不建议非 Core Maintainer 大批量更新依赖因为 umi 涉及依赖预打包需要注意的点很多。执行pnpm dep:update更新依赖即pnpm up --interactive --latest --recursive交互式选择升级到最新版本。由于 umi 会预打包部分依赖更新依赖后需要检查更新的依赖是否在 devDependencies 中、是否已被预打包。如果是则在对应包中执行pnpm build:deps并指定要更新的预打包依赖文件$ pnpm build:deps --dep webpack-manifest-pluginbuild:deps在包级脚本中对应umi-scripts bundleDeps实现见 scripts/bundleDeps.ts它依据各包package.json中compiledConfig声明的依赖清单重新生成compiled目录下的预打包文件如umijs/plugin-docs就在compiledConfig.deps中声明了mdx-js/mdx、rehype-slug、remark-gfm、rehype-autolink-headings等需要打进compiled目录的依赖。发布只有 Core Maintainer 才能执行发布。umi 目前已改用npm Trusted Publishing / OIDC因此本地发布命令只负责提升版本号、创建并推送 release commit/tag不再在本地执行npm publish$ pnpm releasepnpm release对应 scripts/release.ts其执行流水线依次为检查 git 状态干净、检查远端无落后、检查 npm registry 必须是官方源https://registry.npmjs.org/、通过lerna changed校验有变更的包、运行npm run check:packageFiles、清理各包dist、执行npm run build:release构建产物、用lerna version提升版本并生成latest/next/canary三种 npm tag根据版本号中是否包含-alpha./-beta./-rc.或-canary.、同步 examples 的 start 脚本、更新 pnpm lockfile最后提交release: versioncommit 并打 tag 推送到远端。推送之后GitHub Actions 的 Release workflow 通过 OIDC 获取 npm 发布权限运行pnpm release:publish即 scripts/releasePublish.ts将各包依次发布到 npm 并携带--provenance参数。该脚本会先通过npm view检查版本是否已发布已发布则跳过再在临时目录用pnpm pack打包、解包后执行npm publish --tag tag --access public --provenance同时支持--dry-run试跑发布顺序上先发布除umi/max外的依赖包最后发布umi与max两个聚合包。通过 dist-tag 回滚例如要回滚到 4.0.81$ pnpm -rc --filter ./packages/** exec pnpm dist-tag add \$PNPM_PACKAGE_NAME4.0.81 latest该命令对packages下所有子包递归执行pnpm dist-tag add把对应包的latestdist-tag 指回旧版本号从而实现不重新发版即可把默认安装版本回退。加入贡献者群凡提交过 Bugfix 或 Feature 类型 PR 且有兴趣参与 umi 维护的开发者可先用钉钉扫描官方文档中的二维码备注你的 GitHub id维护者会把你拉入贡献者群。如果你暂时不知道可以贡献什么可以在源码中搜索TODO或FIXME标记从这些待办点入手开始你的第一个 PR。【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考