本地开发
本文介绍如何在本地跑通 Birdpaper UI 仓库：启动文档站、开发组件、跑测试与本地联调。
环境要求
- Node.js ≥ 18（CI 使用 Node 20）
- pnpm 8（仓库
packageManager为pnpm@8.10.4）
建议使用 Corepack 启用指定 pnpm：
bash
corepack enable
corepack prepare pnpm@8.10.4 --activate克隆与安装
bash
git clone https://github.com/birdpaper-team/birdpaper-ui.git
cd birdpaper-ui
pnpm install本仓库是 pnpm monorepo，主要包：
| packages/components | 组件源码与单测 |
| packages/theme | 主题 SCSS / CSS 变量 |
| packages/hooks | 公共 hooks |
| packages/birdpaper-ui | 对外入口与安装器 |
| docs | VitePress 文档站 |
启动文档站
日常开发以文档站为预览环境（组件通过 workspace 直接引用源码）：
bash
pnpm docs:dev默认地址：http://localhost:7070/。
修改 packages/components 或 packages/theme 后，文档页一般会热更新。若样式未刷新，重启 docs:dev。
其他文档命令：
bash
pnpm docs:build # 构建（base: /birdpaper-ui/）
pnpm docs:build:root # 构建（base: /）
pnpm docs:preview # 预览构建产物（默认 8080）目录与开发约定
以 Button 为例，组件目录大致如下：
text
packages/components/button/
├── index.ts # 导出
├── src/
│ ├── button.vue # 组件实现
│ ├── props.ts
│ └── types.ts
├── style/index.ts # 引入主题样式
└── __tests__/button.test.ts对应主题样式：
text
packages/theme/src/button.scss文档与示例：
text
docs/src/components/button/
├── index.md # 组件页
├── demo.md # 演示说明
└── api.md # API
docs/src/example/button/
├── basic.vue
└── ...新增组件时通常需要同步：
- 在
packages/components/<name>/实现组件并导出 - 在
packages/components/index.ts增加导出 - 在
packages/birdpaper-ui/components.ts（及插件类如有）注册 - 在
packages/theme/src/增加样式，并写入packages/theme/src/index.scss - 在
docs/src/components/、docs/src/example/补充文档与示例 - 在侧边栏
docs/src/.vitepress/config/locales/zh-CN/sidebar.ts（及英文侧栏若有）登记
常用命令
| pnpm docs:dev | 启动文档开发服务 |
| pnpm test | 运行 Vitest |
| pnpm vitest:ui | Vitest UI |
| pnpm lint | oxlint 检查 |
| pnpm build | 清理并构建产物到 dist/ |
| pnpm yalc | 构建后通过 yalc 推送到本地联调 |
| pnpm cz | 交互式规范提交（czg emoji） |
| pnpm clean | 清理构建缓存 / dist |
跑单个组件测试示例：
bash
pnpm test packages/components/button
# 或
pnpm exec vitest run packages/components/button本地联调业务项目
需要在真实业务仓库验证未发布改动时，可用 yalc：
bash
# 在 birdpaper-ui 仓库
pnpm yalc
# 在业务项目
yalc add birdpaper-ui
# 按需重启业务 dev server更新组件后再次执行 pnpm yalc 推送。联调结束可在业务项目执行 yalc remove birdpaper-ui 并恢复 npm 依赖。
也可使用 pnpm link / workspace protocol，按团队习惯选择即可。
构建产物
bash
pnpm build产物输出到 dist/birdpaper-ui（含组件包与 theme/*.css）。版本变更见 更新日志。
调试建议
- 优先在文档示例中复现：改
docs/src/example/**最快验证交互与样式 - 样式问题：确认是否改到了
packages/theme，以及是否已在index.scss引入 - 类型问题：组件
props/types与文档api.md保持一致 - 深色模式：文档站可切换外观；主题变量规则见 定制主题 与 深色模式