企业官网建设流程全解析

• 前端
• UI组件
• 设计系统

Vue DevUI（仓库即 DevCloudFE/vue-devui）是一个基于 Vue 3 与 Vite 构建的开源组件库，其根目录的 CONTRIBUTING.md 给出了从零参与开发的标准路径：使用 pnpm 构建 monorepo、认领 issue、Fork 仓库、遵循 Angular Commit Message 规范提交、通过 ESLint 与单元测试门禁后合入 PR。读完本文，你将掌握在 vue-devui 仓库中搭建本地开发环境、发起合规 PR、为新组件补齐文档与测试，以及用code-check命令自查代码质量的全套实战技能。

一、仓库结构与环境准备：pnpm monorepo 是怎么组织的

Vue DevUI 采用 pnpm 管理的 monorepo 结构，根目录的 pnpm-workspace.yaml 声明了 workspace 范围：

packages: - 'packages/**'

所有可发布的包都位于packages/目录下，包括：

• packages/devui-vue：组件库主体包，即贡献者最常打交道的部分；
• packages/devui-cli：CLI 工具包，提供组件模板创建、代码检查、打包发布等命令；
• packages/devui-theme：主题变量与主题管理包。

其中packages/devui-vue/package.json中name字段为vue-devui（当前版本 1.6.36），所有针对组件库本身的操作都要通过pnpm --filter vue-devui来定向执行。根目录 package.json 也提前封装好了常用脚本，例如：

{ "dev": "pnpm --filter vue-devui dev", "build": "pnpm --filter vue-devui build", "build:lib": "pnpm --filter vue-devui build:lib", "test": "pnpm --filter vue-devui tests.test" }

所以你在根目录直接执行pnpm dev、pnpm build、pnpm test，就会自动转发给vue-devui包处理。

关于 pnpm 版本的注意事项

原贡献指南明确要求使用 pnpm 6.x，理由是 pnpm 7.x 发生了 breaking change。从仓库实际依赖来看，根目录devDependencies中 pin 了husky@7.0.4、lint-staged@11.2.6、@commitlint/cli@^11.0.0，组件库包内还使用了vitepress@0.20.1、vite@2.4.4等较早期工具链，因此建议严格按仓库现状选择匹配的 Node.js 与 pnpm 版本，避免因包管理器或运行时升级引发异常。若坚持使用 pnpm 7.x，需要自行修改相关 script，例如本地启动改为pnpm --filter vue-devui dev（根目录脚本已内置这种转发写法，可直接复用）。

二、快速上手：5 步跑起本地组件库网站

参与devui-vue的开发或测试，先完成环境搭建。原指南的步骤与命令如下：

1. 点击仓库右上角的 Fork 按钮，将仓库 Fork 到个人空间；
2. Clone 个人空间项目到本地；
3. 在 Vue DevUI 根目录运行pnpm i安装依赖；
4. 运行pnpm dev启动组件库网站；
5. 用浏览器访问 http://localhost:3000/。

完整命令序列（执行前请将username替换为你的 GitHub 用户名）：

git clone git@github.com:username/vue-devui.git cd vue-devui git remote add upstream git@github.com:DevCloudFE/vue-devui.git pnpm i pnpm dev

这里git remote add upstream是为了后续能同步上游仓库的最新代码。补充两个贴近实际开发的细节：

• pnpm dev实际执行的是pnpm generate:theme && vitepress dev docs（见 packages/devui-vue/package.json），即先由 devui-cli 生成主题变量文件，再启动 VitePress 文档站点；
• 若只想跑纯组件演示站点，可以改用根目录脚本pnpm dev:site（等价于vite --port 3010），此时站点运行在 3010 端口，而不是文档站点的 3000 端口。

三、参与贡献：从认领 Issue 到 PR 合入的完整流程

Vue DevUI 是多人协作的开源项目，为了避免多人同时开发同一个组件或功能，先到 issues 列表中选择感兴趣的任务并在评论区认领，再进入以下流程：

1. 确认已完成快速上手步骤，能正常访问本地站点；
2. 创建新分支：git checkout -b username/feature1，分支名建议为username/feat-xxx/username/fix-xxx；
3. 本地编码，遵循开发规范（见下文第四节）；
4. 遵循 Angular Commit Message 格式提交（不符合规范的提交将不会被合并）；
5. 推送到 Fork 后的远程仓库：git push origin branchName； 6.（可选）同步上游仓库 dev 分支最新代码：git pull upstream dev；
6. 打开上游仓库提交 PR；
7. 仓库 Committer 进行 Code Review 并提出意见；
8. PR 发起人根据意见调整代码（同一分支发起 PR 后，后续 commit 会自动同步，无需重新开 PR）；
9. 仓库管理员合并 PR，贡献流程结束。

提交规范：commitlint 的硬性约束

所谓“遵循 Angular Commit Message 格式”，在仓库中由根目录的 commitlint.config.js 强制执行：

const types = ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'release', 'chore', 'revert']; module.exports = { extends: ['@commitlint/config-conventional'], rules: { 'type-empty': [2, 'never'], 'type-enum': [2, 'always', types], 'scope-case': [0, 'always'], 'subject-empty': [2, 'never'], 'subject-case': [0, 'never'], 'header-max-length': [2, 'always', 88], }, };

从配置可以解读出几个硬性要求：

• type-empty: [2, 'never']与type-enum：提交信息必须以feat、fix、docs、style、refactor、perf、test、build、release、chore、revert之一开头，type 不能为空；
• subject-empty: [2, 'never']：主题描述不能为空；
• header-max-length: [2, 'always', 88]：提交信息首行（header）长度不能超过 88 个字符；
• scope-case与subject-case被显式放宽（severity 为 0），不对大小写作强制要求。

同时，根目录package.json中通过prepare: husky install注册了 Git Hooks，precommit阶段会触发lint-staged对暂存文件执行eslint --fix（样式文件执行stylelint --fix）。也就是说，本地提交时就会自动完成一部分代码修正。另外，原指南还提醒：提交之前需要为 Commit 添加 GPG 签名。

新增组件或组件新特性时的附加要求

如果贡献涉及新组件或组件的新特性，还需完成三件事：

1. 完善组件中英文文档；
2. 完善组件的单元测试；
3. 完成组件自检清单。

组件文档在仓库中的落点是packages/devui-vue/docs/components/下各组件目录的.md文件，例如 button 组件文档、alert 组件文档；单元测试则放在各组件目录的__tests__/下，例如 alert.spec.ts、button.spec.tsx。

四、开发规范速览：四份子文档贯穿组件开发全程

贡献指南要求本地编码时遵循开发规范，其索引文档位于 packages/devui-vue/docs/contributing/development-specification/index.md，规范分为四部分：

1. 组件目录和文件组织规范：规定每个组件目录下src/、index.ts、测试与文档的组织方式；
2. 组件 API 和 Demo 设计规范：规定组件对外 API 与示例的设计约定；
3. 组件 API 和 Demo 文档规范：规定文档中 API 表格与 Demo 的书写要求；
4. 组件编码规范：规定 TS/TSX/SCSS 的具体编码风格。

从仓库实际结构看，各组件普遍遵循组件名/src/*.tsx|*.ts|*.scss + 组件名/index.ts + __tests__/*.spec.ts(x)的布局，例如 alert 组件 下包含src/、__tests__/和index.ts，这正与上述目录组织规范相印证。

五、代码检查：ESLint 与单元测试门禁详解

代码提交前会自动执行 ESLint 检查，GitHub PR 合入门禁中也配置了 ESLint 任务。ESLint 检查不通过，PR 将无法合入。因此提交前务必手动执行代码检查。

code-check 命令的使用

code-check是 devui-cli 提供的内置命令，其命令定义见 packages/devui-vue/devui-cli/index.js：

program .command('code-check') .option('-c --components <components>', '组件名称（支持英文逗号分隔）') .addOption(new Option('-t --type <type>', '代码检查类型').choices(['eslint', 'unit-test'])) .description('代码检查') .action(codeCheck);

• -t, --type：必选项之一，只能是eslint或unit-test（由.choices()限定）；
• -c, --components：可选，组件名称，支持英文逗号分隔，可只检查指定组件；不传则检查全部已发布组件。

原指南给出的标准命令如下：

# 执行 ESLint 检查 pnpm cli --filter vue-devui -- code-check -t eslint pnpm cli --filter vue-devui -- code-check -t eslint -c alert,button # 执行单元测试 pnpm cli --filter vue-devui -- code-check -t unit-test pnpm cli --filter vue-devui -- code-check -t unit-test -c alert,button

其中pnpm cli --filter vue-devui对应packages/devui-vue/package.json中的"cli": "node ./devui-cli/index.js"，即直接调用仓库自带的 devui-cli 入口。

底层实现：code-check 到底做了什么

实现位于 packages/devui-vue/devui-cli/commands/code-check.js，核心逻辑可以梳理为：

1. 确定待检查组件集合

const completeComponents = fs.readdirSync(entryDir).filter((name) => { const componentDir = path.resolve(entryDir, name); const isDir = fs.lstatSync(componentDir).isDirectory(); return isDir && fs.readdirSync(componentDir).includes('index.ts') && isReadyToRelease(name); });

它扫描packages/devui-vue/devui目录，只把「包含index.ts且通过isReadyToRelease判断（来自 shared/utils.js）」的目录视为可检查组件。未传-c时逐个检查全部组件；传了-c则按逗号分隔逐个执行。

2. ESLint 检查

const eslintResult = await shell.exec(`eslint --color "./devui/${name}/**/{*.ts,*.tsx}"`); if (eslintResult.stdout !== '') { shell.echo(chalkError('Error: ESLint failed.')); shell.exit(1); }

对目标组件的全部.ts/.tsx文件运行eslint，只要 stdout 非空即判定失败并直接以状态码 1 退出，这正是“检查不通过 PR 无法合入”的本地版实现。

3. 单元测试检查

单组件测试通过 jest 的testMatch精确匹配目标组件目录：

shell.exec(`pnpm test --filter vue-devui -- \ --colors --noStackTrace --testMatch **/**/${name}/**/*.spec.{ts,tsx}`)

全量测试则直接执行pnpm --filter vue-devui test --reporter default，只要 stderr 中出现failed或ERR_就中断并以失败退出。仓库的 jest.config.js 中testMatch: ['**/**/*.spec.(ts|tsx)']与组件包内devDependencies里的jest@27、@vue/test-utils@2.0.0-rc.9、babel-jest等共同构成了测试运行环境，样式文件与静态资源分别由 style-mock.ts 与 file-mock.ts mock 掉。

手动执行全量测试的其他入口

除code-check外，根目录的pnpm test与组件包内的pnpm --filter vue-devui test（等价于jest --config jest.config.js）也可以直接运行全量单元测试；若需要覆盖率报告，可执行组件包内的pnpm --filter vue-devui coverage（jest --config jest.config.js --coverage）。

六、FAQ 与常见坑位

Q1：pnpm i安装失败怎么办？确认 pnpm 主版本与仓库工具链匹配（原指南推荐 6.x）；monorepo 依赖较多，安装耗时长属正常现象，耐心等待输出结束即可。

Q2：pnpm dev启动的站点打不开？确认是否按顺序先执行了pnpm generate:theme（pnpm dev已自动包含），并检查 3000 端口是否被占用；纯演示站点用pnpm dev:site时端口为 3010。

Q3：提交时被 commitlint 拦截？检查 type 是否为 commitlint.config.js 枚举的 11 种之一，且 header 不超过 88 字符。

Q4：PR 门禁失败但本地没发现问题？先跑pnpm cli --filter vue-devui -- code-check -t eslint全量检查，确认新改动的组件目录下有index.ts且能通过isReadyToRelease判断，否则该组件根本不会进入检查范围。

总结

参与 Vue DevUI 贡献的完整闭环是：认领 issue → Fork + Clone →pnpm i装依赖 →pnpm dev本地预览 → 按分支规范开发（遵循开发规范四件套）→ 按 Angular Commit 格式并附 GPG 签名提交 → 用code-check -t eslint / -t unit-test自查 → 推送分支并发起 PR → 响应 Code Review → 合入。本文所有命令与约束均以仓库根目录 CONTRIBUTING.md、package.json、commitlint.config.js 及 devui-cli 的 code-check.js 实现为准，按此流程操作即可顺利通过门禁、完成你的第一次贡献。

• 前端
• UI组件
• 设计系统