Element Plus 贡献指南从环境搭建、本地开发到提交 PR 的完整流程【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusElement Plus 是一个使用 TypeScript 编写的 Vue 3 UI 组件库采用 pnpm workspace 单仓库monorepo结构。本文以仓库根目录的 CONTRIBUTING.md 为纲系统讲解为 Element Plus 提交代码贡献的完整路径如何规范地提交 Issue、搭建本地开发环境、运行文档站与 Playground、编译源码与文档以及如何写出符合 Conventional Commits 规范的提交信息并顺利合入 Pull Request。读完本文你将掌握一套可直接落地执行的 Element Plus 贡献工作流并理解仓库中各条工程化约束背后的源码依据。一、提交 Issue贡献的第一步在动手写代码之前先学会正确地反馈问题。贡献指南对 Issue 的提交提出了三点明确要求先搜索再提问提交 Issue 前务必先用关键词搜索确认你遇到的问题是否已被他人报告过避免重复提交。通过 Issue 模板提交Issue 应通过官方模板填写并尽可能提供足够的信息以复现问题方便维护者验证与修复。信息不足会被直接关闭指南中明确强调——Issues with insufficient information WILL BE CLOSED directly because we cannot reproduce them.信息不足的 Issue 因无法复现会被直接关闭。此外涉及**功能请求feature request**的 Issue 应提交到独立的 RFC 仓库中这有助于团队更高效地管理功能需求也让核心仓库的 Issue 列表保持聚焦于缺陷与可复现问题。二、开发环境准备Prerequisites想要参与 Element Plus 的开发你的机器需要满足以下版本要求工具最低版本要求Node.js 22.13.0pnpm 11Git 2.20Node.js 版本要求是有具体原因的指南说明部分编译产物依赖 Node.js 22.13.0 中引入的特性。这一点在仓库配置中得到了印证——根目录 package.json 的engines字段声明了node: 22.13.0而packageManager字段则固定为pnpm11.24.0。这意味着即使你本地安装了其他包管理器如 npm、yarn仓库也推荐且主要围绕 pnpm 工作流运行建议遵循packageManager声明使用对应的 pnpm 版本。三、克隆仓库与初始化项目标准的操作路径是在仓库主页点击右上角的Fork按钮将仓库复制到自己的账号下将 Fork 后的项目下载clone到本地运行以下命令完成项目引导cd $THE_PROJECT_PATH_YOU_DOWNLOADED # 如果尚未安装依赖 pnpm installpnpm install并不是一次简单的依赖安装。结合根目录 package.json 的钩子配置可以看到安装完成后会自动触发postinstall脚本依次执行pnpm stub生成源码桩文件、pnpm gen:version生成版本文件以及internal/metadata的元数据构建。同时仓库在prepare阶段还会安装 husky用于在提交时自动挂载 Git 钩子。此外安装过程中pnpm gen:version即 scripts/gen-version.ts会读取packages/element-plus/package.json中的版本号并写入version.ts供全库共享版本信息。四、验证安装是否成功依赖安装完成后建议先运行两条命令验证环境是否正常pnpm t pnpm formatpnpm t对应根目录脚本中的test即vitest。从 vitest.config.mts 可以看到测试环境基于jsdom并配置了vitest.setup.ts作为 setup 文件组件测试放在各组件目录的__tests__/下例如packages/components/button/__tests__/。pnpm format对应prettier --write --experimental-cli .会按项目统一风格格式化整个仓库。如果这两条命令都能顺利跑完说明开发环境已经就绪。另外根目录还提供了pnpm lintESLint 全量检查、pnpm typecheck类型检查等质量关卡这些在提交 PR 前都是 CI 会校验的内容。五、开始开发三种工作场景确认环境无误后根据你的目标选择对应的开发方式。5.1 修改与更新文档站Element Plus 的官方文档站基于 VitePress 构建源码位于docs目录参见 docs/package.json 中vitepress依赖。如果你想修改文档站本身运行pnpm docs:gen-locale # 生成本地开发所需的 locale 文件 pnpm docs:dev其中docs:gen-locale对应pnpm -C docs gen-locale其作用是根据 Crowdin 配置生成各语言的本地化文件docs:dev则会在本地启动 VitePress 开发服务器供你实时预览文档改动。5.2 修改组件使用本地 Playground如果你想针对某个具体组件进行改动和调试运行pnpm dev这条命令对应pnpm -C play dev会启动play目录下的本地 Playground 工程。结合 play/app.example.vue 可以看到Playground 是一个可自由改写的 Vue 应用模板内置了el-icon、el-button、v-loading等组件的使用示例你可以在其中替换为自己正在开发的组件进行手测。仓库还提供了更详细的本地开发指引即仓库内的 docs/en-US/guide/dev-guide.md其中建议将正在开发的组件写入play/src/App.vue并按需修改。另外如果你需要从零开发一个全新组件可以使用脚手架命令pnpm gen component-name底层脚本为 scripts/gc.sh。该脚本会自动在packages/components/下生成组件目录骨架包括src/*.vue模板文件、src/*.ts的 props/emits 定义、instance.ts实例类型、__tests__/*.test.tsx单元测试、style/index.ts与style/css.ts样式入口、对应的theme-chalkSCSS 文件并自动把新组件注册到 packages/components/index.ts 和全局类型声明中是快速起步的捷径。5.3 编译源码需要在本地产出发布到 npm 的编译产物时运行pnpm build该命令对应pnpm run -C internal/build start会驱动仓库内部的构建工具链将packages下的各模块编译打包。构建入口与工具实现在internal目录下internal/build仓库根目录的package.json脚本中还提供了pnpm build:theme用于只构建packages/theme-chalk的主题样式。5.4 编译文档网站如果希望在本地产出文档站的静态构建产物运行pnpm docs:build对应docs包的build脚本会先执行gen-llms生成面向 LLM 的索引文件再调用vitepress build完成文档站构建之后可用pnpm docs:serve本地预览构建结果。六、Pull Requests提交代码的检查清单完成编码任务后提交 PR 前请逐项确认以下事项更新测试以覆盖所有场景新增逻辑必须有对应的测试用例修复缺陷则建议补充针对性的回归测试新组件默认就带有一个最小可运行的render test。改动 API 时同步更新文档如果修改了组件对外暴露的 props、事件、插槽或类型必须同步更新docs目录下对应的组件文档。撰写完整的提交信息遵循仓库的 Conventional Commits 规范详见下一节。推送本地分支并提交 PR将改动推到自己的 Fork 远端再向 upstream上游仓库发起 Pull Request。在 PR 描述中补充上下文在 description 中尽量说明改动背景与意图帮助 reviewer 更快理解变更的来龙去脉。七、文档格式规范Documentation Formatting Guidelines当更新文档中的 API 表格时需要保持描述的一致性遵循四条约定属性和 prop 名称保持小写API 描述以大写字母开头保留反引号包裹的代码术语例如slot、Tooltip、Popover避免与本次文档更新无关的大范围格式调整减少 review 噪音。这些约定与仓库的工程规范一脉相承——AGENTS.md 中同样强调“避免无关重构与格式化改动”并建议公共 API 变更必须配套文档更新、同步 props/events/slots 类型定义。八、Commit 规范统一且机器可校验Element Plus 要求所有提交信息遵循 Conventional Commits 规范且格式不合规的 PR 将不会被接受原文明确标注PRs with unformatted commit messages WILL NOT BE ACCEPTED.。8.1 使用交互式 CLI 生成提交信息推荐方式pnpm czcz对应根目录脚本中的czgcz-git的实现会启动交互式 CLI 引导你一步步选择 type、scope、填写 subject 与 body自动生成符合规范的提交信息避免手写出错。仓库在package.json的config.commitizen中已预设好适配路径。8.2 手动书写时的格式要求你当然也可以手写提交信息但必须遵守规则。提交信息头subject的格式为type: [messages]结合仓库的 commitlint.config.mjs可以确认以下硬性约束type 枚举type-enum规则见 commitlint.config.mjsbuild、chore、ci、docs、feat、fix、perf、refactor、revert、release、style、test、improvement共 13 种type 必须小写且不能为空。scope 枚举scope-enum规则scope 自动取自packages目录下的所有包、internal目录下的工具包外加docs、play、project、core、style、ci、dev、deploy等固定值scope 必须为小写。配置中还做了智能化处理cz交互时会根据git status中改动所在的包自动推荐默认 scope 与 subject 前缀减少手输成本。长度与格式header-max-length限定 header 不超过 72 字符subject不能为空、不能以句号结尾、不允许 sentence-case/start-case/pascal-case/upper-case 等大写风格body与footer前需保留空行body-leading-blank、footer-leading-blank。一个符合规范的提交示例来自 docs/en-US/guide/commit-examples.mdfeat(components): [button] I did something with button Blank between subject and body is expected.(period is expected) Describes your change in one line or multi-line. Capitalize your first letter when starting a new line Please do not exceeds 72 characters per line, because that would be harder to comprehend. - You can also add bullet list symbol for better layout规范的提交信息带来两个直接收益一是让 reviewer 一眼看清贡献者的意图二是可以自动生成 changelog这也是仓库维护发布记录的基石。九、配套的本地质量关卡在正式提交 PR 之前建议在本地完整跑一遍仓库提供的基础校验确保改动通过 CI 的门槛各命令均定义于 package.json命令作用pnpm test运行 Vitest 单元测试含组件测试与 hooks/utils 测试pnpm test:coverage运行测试并输出覆盖率报告pnpm lintESLint 全量检查--max-warnings 0零容忍警告pnpm typecheck依次执行 web/play/node/vite-config/vitest 五套 tsconfig 的类型检查pnpm formatPrettier 全仓格式化pnpm test:ssr基于 ssr-testing/vitest.config.ts 的服务端渲染冒烟测试此外仓库还通过 lint-staged见 package.json在 Git 提交时对暂存文件自动执行eslint --fix与prettier --write让格式问题在源头被拦截。十、结语贡献流程全景回顾整个贡献流程搜索并规范提交 Issue功能请求走 RFC→ 确认 Node.js/pnpm/Git 版本 → Fork 并pnpm install初始化 →pnpm t与pnpm format验证环境 → 按场景选择pnpm docs:dev文档站/pnpm dev组件 Playground/pnpm build编译产物→ 补充测试与文档 → 用pnpm cz生成规范提交信息 → 推送并提交 PR。每一步背后都有仓库的工程化配置作为支撑engines约束运行时、husky 挂载 Git 钩子、commitlint 强制提交规范、Vitest 守护测试质量。遵循这套流程你的贡献就能顺畅地汇入 Element Plus 的迭代之中。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Element Plus 贡献指南：从环境搭建、本地开发到提交 PR 的完整流程
Element Plus 贡献指南从环境搭建、本地开发到提交 PR 的完整流程【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusElement Plus 是一个使用 TypeScript 编写的 Vue 3 UI 组件库采用 pnpm workspace 单仓库monorepo结构。本文以仓库根目录的 CONTRIBUTING.md 为纲系统讲解为 Element Plus 提交代码贡献的完整路径如何规范地提交 Issue、搭建本地开发环境、运行文档站与 Playground、编译源码与文档以及如何写出符合 Conventional Commits 规范的提交信息并顺利合入 Pull Request。读完本文你将掌握一套可直接落地执行的 Element Plus 贡献工作流并理解仓库中各条工程化约束背后的源码依据。一、提交 Issue贡献的第一步在动手写代码之前先学会正确地反馈问题。贡献指南对 Issue 的提交提出了三点明确要求先搜索再提问提交 Issue 前务必先用关键词搜索确认你遇到的问题是否已被他人报告过避免重复提交。通过 Issue 模板提交Issue 应通过官方模板填写并尽可能提供足够的信息以复现问题方便维护者验证与修复。信息不足会被直接关闭指南中明确强调——Issues with insufficient information WILL BE CLOSED directly because we cannot reproduce them.信息不足的 Issue 因无法复现会被直接关闭。此外涉及**功能请求feature request**的 Issue 应提交到独立的 RFC 仓库中这有助于团队更高效地管理功能需求也让核心仓库的 Issue 列表保持聚焦于缺陷与可复现问题。二、开发环境准备Prerequisites想要参与 Element Plus 的开发你的机器需要满足以下版本要求工具最低版本要求Node.js 22.13.0pnpm 11Git 2.20Node.js 版本要求是有具体原因的指南说明部分编译产物依赖 Node.js 22.13.0 中引入的特性。这一点在仓库配置中得到了印证——根目录 package.json 的engines字段声明了node: 22.13.0而packageManager字段则固定为pnpm11.24.0。这意味着即使你本地安装了其他包管理器如 npm、yarn仓库也推荐且主要围绕 pnpm 工作流运行建议遵循packageManager声明使用对应的 pnpm 版本。三、克隆仓库与初始化项目标准的操作路径是在仓库主页点击右上角的Fork按钮将仓库复制到自己的账号下将 Fork 后的项目下载clone到本地运行以下命令完成项目引导cd $THE_PROJECT_PATH_YOU_DOWNLOADED # 如果尚未安装依赖 pnpm installpnpm install并不是一次简单的依赖安装。结合根目录 package.json 的钩子配置可以看到安装完成后会自动触发postinstall脚本依次执行pnpm stub生成源码桩文件、pnpm gen:version生成版本文件以及internal/metadata的元数据构建。同时仓库在prepare阶段还会安装 husky用于在提交时自动挂载 Git 钩子。此外安装过程中pnpm gen:version即 scripts/gen-version.ts会读取packages/element-plus/package.json中的版本号并写入version.ts供全库共享版本信息。四、验证安装是否成功依赖安装完成后建议先运行两条命令验证环境是否正常pnpm t pnpm formatpnpm t对应根目录脚本中的test即vitest。从 vitest.config.mts 可以看到测试环境基于jsdom并配置了vitest.setup.ts作为 setup 文件组件测试放在各组件目录的__tests__/下例如packages/components/button/__tests__/。pnpm format对应prettier --write --experimental-cli .会按项目统一风格格式化整个仓库。如果这两条命令都能顺利跑完说明开发环境已经就绪。另外根目录还提供了pnpm lintESLint 全量检查、pnpm typecheck类型检查等质量关卡这些在提交 PR 前都是 CI 会校验的内容。五、开始开发三种工作场景确认环境无误后根据你的目标选择对应的开发方式。5.1 修改与更新文档站Element Plus 的官方文档站基于 VitePress 构建源码位于docs目录参见 docs/package.json 中vitepress依赖。如果你想修改文档站本身运行pnpm docs:gen-locale # 生成本地开发所需的 locale 文件 pnpm docs:dev其中docs:gen-locale对应pnpm -C docs gen-locale其作用是根据 Crowdin 配置生成各语言的本地化文件docs:dev则会在本地启动 VitePress 开发服务器供你实时预览文档改动。5.2 修改组件使用本地 Playground如果你想针对某个具体组件进行改动和调试运行pnpm dev这条命令对应pnpm -C play dev会启动play目录下的本地 Playground 工程。结合 play/app.example.vue 可以看到Playground 是一个可自由改写的 Vue 应用模板内置了el-icon、el-button、v-loading等组件的使用示例你可以在其中替换为自己正在开发的组件进行手测。仓库还提供了更详细的本地开发指引即仓库内的 docs/en-US/guide/dev-guide.md其中建议将正在开发的组件写入play/src/App.vue并按需修改。另外如果你需要从零开发一个全新组件可以使用脚手架命令pnpm gen component-name底层脚本为 scripts/gc.sh。该脚本会自动在packages/components/下生成组件目录骨架包括src/*.vue模板文件、src/*.ts的 props/emits 定义、instance.ts实例类型、__tests__/*.test.tsx单元测试、style/index.ts与style/css.ts样式入口、对应的theme-chalkSCSS 文件并自动把新组件注册到 packages/components/index.ts 和全局类型声明中是快速起步的捷径。5.3 编译源码需要在本地产出发布到 npm 的编译产物时运行pnpm build该命令对应pnpm run -C internal/build start会驱动仓库内部的构建工具链将packages下的各模块编译打包。构建入口与工具实现在internal目录下internal/build仓库根目录的package.json脚本中还提供了pnpm build:theme用于只构建packages/theme-chalk的主题样式。5.4 编译文档网站如果希望在本地产出文档站的静态构建产物运行pnpm docs:build对应docs包的build脚本会先执行gen-llms生成面向 LLM 的索引文件再调用vitepress build完成文档站构建之后可用pnpm docs:serve本地预览构建结果。六、Pull Requests提交代码的检查清单完成编码任务后提交 PR 前请逐项确认以下事项更新测试以覆盖所有场景新增逻辑必须有对应的测试用例修复缺陷则建议补充针对性的回归测试新组件默认就带有一个最小可运行的render test。改动 API 时同步更新文档如果修改了组件对外暴露的 props、事件、插槽或类型必须同步更新docs目录下对应的组件文档。撰写完整的提交信息遵循仓库的 Conventional Commits 规范详见下一节。推送本地分支并提交 PR将改动推到自己的 Fork 远端再向 upstream上游仓库发起 Pull Request。在 PR 描述中补充上下文在 description 中尽量说明改动背景与意图帮助 reviewer 更快理解变更的来龙去脉。七、文档格式规范Documentation Formatting Guidelines当更新文档中的 API 表格时需要保持描述的一致性遵循四条约定属性和 prop 名称保持小写API 描述以大写字母开头保留反引号包裹的代码术语例如slot、Tooltip、Popover避免与本次文档更新无关的大范围格式调整减少 review 噪音。这些约定与仓库的工程规范一脉相承——AGENTS.md 中同样强调“避免无关重构与格式化改动”并建议公共 API 变更必须配套文档更新、同步 props/events/slots 类型定义。八、Commit 规范统一且机器可校验Element Plus 要求所有提交信息遵循 Conventional Commits 规范且格式不合规的 PR 将不会被接受原文明确标注PRs with unformatted commit messages WILL NOT BE ACCEPTED.。8.1 使用交互式 CLI 生成提交信息推荐方式pnpm czcz对应根目录脚本中的czgcz-git的实现会启动交互式 CLI 引导你一步步选择 type、scope、填写 subject 与 body自动生成符合规范的提交信息避免手写出错。仓库在package.json的config.commitizen中已预设好适配路径。8.2 手动书写时的格式要求你当然也可以手写提交信息但必须遵守规则。提交信息头subject的格式为type: [messages]结合仓库的 commitlint.config.mjs可以确认以下硬性约束type 枚举type-enum规则见 commitlint.config.mjsbuild、chore、ci、docs、feat、fix、perf、refactor、revert、release、style、test、improvement共 13 种type 必须小写且不能为空。scope 枚举scope-enum规则scope 自动取自packages目录下的所有包、internal目录下的工具包外加docs、play、project、core、style、ci、dev、deploy等固定值scope 必须为小写。配置中还做了智能化处理cz交互时会根据git status中改动所在的包自动推荐默认 scope 与 subject 前缀减少手输成本。长度与格式header-max-length限定 header 不超过 72 字符subject不能为空、不能以句号结尾、不允许 sentence-case/start-case/pascal-case/upper-case 等大写风格body与footer前需保留空行body-leading-blank、footer-leading-blank。一个符合规范的提交示例来自 docs/en-US/guide/commit-examples.mdfeat(components): [button] I did something with button Blank between subject and body is expected.(period is expected) Describes your change in one line or multi-line. Capitalize your first letter when starting a new line Please do not exceeds 72 characters per line, because that would be harder to comprehend. - You can also add bullet list symbol for better layout规范的提交信息带来两个直接收益一是让 reviewer 一眼看清贡献者的意图二是可以自动生成 changelog这也是仓库维护发布记录的基石。九、配套的本地质量关卡在正式提交 PR 之前建议在本地完整跑一遍仓库提供的基础校验确保改动通过 CI 的门槛各命令均定义于 package.json命令作用pnpm test运行 Vitest 单元测试含组件测试与 hooks/utils 测试pnpm test:coverage运行测试并输出覆盖率报告pnpm lintESLint 全量检查--max-warnings 0零容忍警告pnpm typecheck依次执行 web/play/node/vite-config/vitest 五套 tsconfig 的类型检查pnpm formatPrettier 全仓格式化pnpm test:ssr基于 ssr-testing/vitest.config.ts 的服务端渲染冒烟测试此外仓库还通过 lint-staged见 package.json在 Git 提交时对暂存文件自动执行eslint --fix与prettier --write让格式问题在源头被拦截。十、结语贡献流程全景回顾整个贡献流程搜索并规范提交 Issue功能请求走 RFC→ 确认 Node.js/pnpm/Git 版本 → Fork 并pnpm install初始化 →pnpm t与pnpm format验证环境 → 按场景选择pnpm docs:dev文档站/pnpm dev组件 Playground/pnpm build编译产物→ 补充测试与文档 → 用pnpm cz生成规范提交信息 → 推送并提交 PR。每一步背后都有仓库的工程化配置作为支撑engines约束运行时、husky 挂载 Git 钩子、commitlint 强制提交规范、Vitest 守护测试质量。遵循这套流程你的贡献就能顺畅地汇入 Element Plus 的迭代之中。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考