1
Monorepo 典型结构（pnpm workspace）：
2

3
my-app/
4
├── apps/
5
│   ├── web/              # 主站
6
│   ├── admin/            # 后台
7
│   ├── mobile/           # H5
8
│   └── docs/             # 文档站
9
├── packages/
10
│   ├── ui/               # 组件库（内部包）
11
│   ├── utils/            # 工具函数
12
│   ├── hooks/            # 自定义 hooks
13
│   ├── request/          # axios 封装
14
│   ├── config-eslint/    # 共享配置
15
│   └── config-tsconfig/  # 共享 ts 配置
16
├── pnpm-workspace.yaml
17
├── turbo.json            # 增量构建配置
18
└── package.json

1
pnpm workspace：包管理器级别
2
- 通过 pnpm-workspace.yaml 定义工作区
3
- 硬链接 + 符号链接：磁盘占用小、安装快
4
- 严格 node_modules 结构，避免"幽灵依赖"
5
- 只解决依赖，不解决构建编排
6

7
Turborepo：任务编排
8
- 基于 turbo.json 声明依赖关系
9
- 增量构建：只构建变更包及其下游
10
- 远程缓存：CI 缓存产物，跨机器复用
11
- Vercel 出品，配置简单，性能好
12

13
Nx：全功能构建系统
14
- 依赖图分析、任务编排、代码生成器
15
- 插件生态（React/Vue/Node/NestJS）
16
- 分布式任务执行
17
- 学习成本高，适合大型企业
18

19
Lerna：老牌工具
20
- v6 后由 Nx 团队维护
21
- 主要用于版本管理和发布（changed/publish）
22
- 构建能力已被 Turborepo/Nx 替代

1
// turbo.json 示例
2
{
3
  "pipeline": {
4
    "build": {
5
      "dependsOn": ["^build"],        // 依赖上游包先构建
6
      "outputs": ["dist/**"]          // 缓存产物
7
    },
8
    "test": { "dependsOn": ["build"] },
9
    "lint": {},
10
    "dev": { "cache": false, "persistent": true }
11
  }
12
}

1
npm/yarn 的问题：
2
1. 每个项目独立 node_modules，重复占用磁盘
3
2. 扁平化 node_modules，产生"幽灵依赖"
4
   （间接依赖可以被 require，但没在 package.json 声明）
5

6
pnpm 的解决方案：
7

8
1. 全局硬链接（Hard Link）
9
   ~/.pnpm-store/v3/files/  →  project/node_modules/.pnpm/
10
   同一版本包在全局只存一份，磁盘节省 60%+
11

12
2. 严格的三层 node_modules 结构
13
   node_modules/
14
   ├── .pnpm/           ← 真实存放（软链到全局 store）
15
   │   ├── lodash@4.17.21/
16
   │   └── ...
17
   └── lodash -> .pnpm/lodash@4.17.21/node_modules/lodash
18
   ↑ 只有 package.json 里声明的依赖才在顶层出现
19

20
3. 内容寻址存储：相同文件只存一份
21
4. 并行安装：比 yarn v1 快 2-3 倍
22

23
带来的收益：
24
- 安装速度：npm ci 60s → pnpm i 15s（真实项目数据）
25
- 磁盘：monorepo 里 10 个 app 共享依赖，节省 90%
26
- 安全：幽灵依赖被杜绝，重构时更可靠

1
// 主应用注册子应用
2
import { registerMicroApps, start } from 'qiankun';
3
registerMicroApps([
4
  {
5
    name: 'sub-vue',
6
    entry: '//localhost:8081',
7
    container: '#subapp',
8
    activeRule: '/vue',
9
    props: { token: getToken },
10
  },
11
]);
12
start({ sandbox: { experimentalStyleIsolation: true } });
13

14
// 子应用导出生命周期（webpack 配置 library）
15
export async function bootstrap() { /* 应用首次加载 */ }
16
export async function mount(props) {
17
  createApp(App).mount(props.container.querySelector('#app'));
18
}
19
export async function unmount() { app.unmount(); }
20

21
// 三大关键机制：
22
// 1. HTML Entry：直接加载子应用 HTML，解析 script/link（比 JS Entry 灵活）
23
// 2. JS 沙箱：Proxy 拦截 window，子应用修改不污染主应用
24
// 3. 样式隔离：Shadow DOM / scoped（选择器加前缀）/ dynamic stylesheet

1
// webpack.config.js（生产者）
2
new ModuleFederationPlugin({
3
  name: 'app_remote',
4
  filename: 'remoteEntry.js',
5
  exposes: { './Button': './src/Button' },
6
  shared: ['react', 'react-dom'],   // 共享依赖，避免重复加载
7
});
8

9
// 消费者
10
new ModuleFederationPlugin({
11
  name: 'app_host',
12
  remotes: { app_remote: 'app_remote@http://x.com/remoteEntry.js' },
13
  shared: ['react', 'react-dom'],
14
});
15

16
// 使用（像本地组件一样）
17
const Button = React.lazy(() => import('app_remote/Button'));

1
1. 样式冲突
2
   - qiankun 用 scoped 加前缀，但全局样式（body、html）改不了
3
   - 解决：约定 BEM 命名 / CSS Module / Shadow DOM
4

5
2. JS 沙箱逃逸
6
   - 定时器、事件监听、全局变量在卸载时要主动清理
7
   - 解决：子应用 mount/unmount 严格管理生命周期
8

9
3. 路由冲突
10
   - 主子应用都有路由，history/popstate 会互相干扰
11
   - 解决：子应用 basename 隔离，主应用做前缀分发
12

13
4. 共享依赖版本不一致
14
   - React 17 主应用 + React 18 子应用共存问题
15
   - 解决：约定版本 / Module Federation shared 强制单例
16

17
5. 通信复杂度
18
   - 跨应用状态同步容易失控
19
   - 解决：qiankun initGlobalState / CustomEvent / URL 参数
20

21
6. 首屏性能
22
   - 加载主应用 + 子应用资源，白屏时间增加
23
   - 解决：预加载（prefetchApps）、子应用 CDN 缓存
24

25
7. 开发调试困难
26
   - 本地要同时起主应用和多个子应用
27
   - 解决：独立运行模式（子应用可脱离主应用启动）

1
完整链路：
2
需求分析 → 技术选型 → 目录结构 → 组件设计 → 构建打包 →
3
文档站 → 单元测试 → 发版流程 → 版本管理 → 迁移方案
4

5
1. 技术选型
6
   - 框架：Vue / React / Web Components（跨框架）
7
   - 样式：Sass / Less / CSS-in-JS / Tailwind / 原子化
8
   - 主题：CSS 变量（推荐，运行时切换）/ Sass 变量（构建时）
9
   - 构建：Vite（开发）+ Rollup（打包）+ Vite lib mode
10

11
2. 目录结构
12
components/
13
├── packages/
14
│   ├── button/
15
│   │   ├── src/Button.vue
16
│   │   ├── __tests__/Button.spec.ts
17
│   │   ├── index.ts               # 导出
18
│   │   └── style/
19
│   │       ├── index.ts           # 样式入口
20
│   │       └── button.scss
21
│   ├── theme-chalk/               # 全局样式变量
22
│   └── utils/                     # 内部工具
23
├── docs/                          # 文档站（VitePress）
24
├── scripts/                       # 构建脚本
25
└── package.json
26

27
3. 组件设计原则
28
   - 单一职责：一个组件只做一件事
29
   - Props 语义清晰：不用 v1、v2 这种命名
30
   - 支持插槽（slot/children）扩展
31
   - 支持 ref 转发（React）/ defineExpose（Vue）
32
   - 无障碍（ARIA 属性、键盘导航）
33
   - 主题变量暴露（--btn-primary-color）
34

35
4. 构建产物（三种格式）
36
   - ESM：dist/es/xxx.js（现代打包器）
37
   - CJS：dist/lib/xxx.js（Node/webpack 老项目）
38
   - UMD：dist/index.js（script 标签直接用）
39
   - 类型声明：dist/types/*.d.ts
40

41
5. 按需引入（关键！）
42
   - 组件独立打包，用户只 import 用到的
43
   - package.json 配置 sideEffects: false
44
   - 提供 unplugin-vue-components 自动导入插件

1
// package.json 关键字段
2
{
3
  "name": "@myorg/ui",
4
  "version": "1.2.0",
5
  "main": "dist/lib/index.js",
6
  "module": "dist/es/index.js",
7
  "types": "dist/types/index.d.ts",
8
  "exports": {
9
    ".": { "import": "./dist/es/index.js", "require": "./dist/lib/index.js" },
10
    "./dist/style.css": "./dist/style.css",
11
    "./es/*": "./es/*",
12
    "./lib/*": "./lib/*"
13
  },
14
  "sideEffects": ["dist/*", "es/*/style/*", "lib/*/style/*"],
15
  "files": ["dist", "es", "lib", "README.md"]
16
}

1
方案 1：CSS 变量（推荐，运行时切换）
2
:root {
3
  --btn-primary-bg: #409eff;
4
  --btn-primary-color: #fff;
5
}
6
.btn-primary {
7
  background: var(--btn-primary-bg);
8
  color: var(--btn-primary-color);
9
}
10
// 用户覆盖：修改 :root 变量即可，无需重新构建
11
// 暗色主题：[data-theme="dark"] { --btn-primary-bg: #333; }
12

13
方案 2：Sass 变量（构建时，性能最好）
14
// 用户在自己的项目里覆盖 $--color-primary 再引入
15
$--color-primary: red;
16
@import "@myorg/ui/theme/index.scss";
17

18
方案 3：CSS-in-JS（运行时，最灵活但性能最差）
19
// styled-components / emotion / vanilla-extract
20
const Button = styled.button`
21
  background: ${props => props.theme.primary};
22
`;
23

24
方案 4：设计 Token（大厂方案）
25
// design-tokens.json → 编译出 CSS 变量 / Sass / JS
26
// 好处：一份 Token 多端复用（Web / 小程序 / iOS / Android）
27

28
实践建议：
29
- 组件库默认 CSS 变量方案（用户改起来最方便）
30
- 内部使用 Sass 变量做构建时优化
31
- 关键 Token 命名规范化（color / spacing / radius / shadow / z-index）
32
- 提供在线主题编辑器（Element Plus Theme）

1
{
2
  "main": "dist/index.cjs.js",       // CJS 入口（老 webpack/node require）
3
  "module": "dist/index.esm.js",     // ESM 入口（webpack/rollup 优先，可 Tree Shaking）
4
  "types": "dist/index.d.ts",        // TypeScript 类型入口
5
  "browser": "dist/index.browser.js",// 浏览器专用（避免 node polyfill）
6
  "unpkg": "dist/index.umd.js",      // CDN script 标签直接用
7
  "exports": {                        // Node 12.7+ 现代入口（优先级最高）
8
    ".": {
9
      "types": "./dist/index.d.ts",
10
      "import": "./dist/index.mjs",
11
      "require": "./dist/index.cjs",
12
      "default": "./dist/index.mjs"
13
    },
14
    "./utils": "./dist/utils/index.mjs",   // 子路径导出
15
    "./style.css": "./dist/style.css",
16
    "./package.json": "./package.json"
17
  },
18
  "sideEffects": false                // 无副作用，可安全 Tree Shaking
19
}
20

21
// exports 的优势：
22
// 1. 明确公开哪些路径（其他路径 import 会报错，防止用户依赖内部实现）
23
// 2. 支持条件导出（node/browser/import/require/types）
24
// 3. 更好的封装性

1
提交前拦截链路：
2

3
编辑器 → ESLint（保存时自动 fix）
4
       ↓
5
git add
6
       ↓
7
husky（Git Hooks）
8
  ├── pre-commit → lint-staged → ESLint + Prettier（只处理暂存文件）
9
  ├── commit-msg → commitlint（校验提交信息规范）
10
  └── pre-push → 单元测试（vitest run）
11
       ↓
12
CI 流水线
13
  ├── 全量 lint
14
  ├── 全量测试 + 覆盖率
15
  ├── 构建产物
16
  └── 部署
17

18
工具职责：
19
- ESLint：代码质量（潜在 bug、最佳实践）
20
- Prettier：代码格式（换行、缩进、引号）
21
- Stylelint：CSS/SCSS 规范
22
- commitlint：提交信息规范
23
- husky：管理 Git Hooks
24
- lint-staged：只对暂存文件跑 lint（快）
25
- Biome：Rust 实现，一个工具替代 ESLint + Prettier（新兴）

1
// lint-staged 配置（package.json）
2
"lint-staged": {
3
  "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
4
  "*.{css,scss,vue}": ["stylelint --fix", "prettier --write"],
5
  "*.{md,json}": ["prettier --write"]
6
}
7

8
// Conventional Commits 规范
9
// feat:     新功能
10
// fix:      bug 修复
11
// docs:     文档变更
12
// style:    代码格式（不影响逻辑）
13
// refactor: 重构
14
// perf:     性能优化
15
// test:     测试
16
// build:    构建/依赖
17
// ci:       CI 配置
18
// chore:    其他杂项
19
// revert:   回滚
20

21
// 例：feat(button): 新增 loading 状态支持
22
// fix(utils): 修复 formatDate 时区问题 #123

1
        /\
2
       /  \  E2E（10%）
3
      /----\   真实浏览器跑完整用户流程
4
     /      \  Playwright / Cypress
5
    /--------\
6
   /   集成    \  集成测试（20%）
7
  /    测试     \  多组件协作、组件 + 状态管理
8
 /--------------\  Testing Library + MSW
9
/   单元测试      \  单元测试（70%）
10
/  （最多、最快）   \  纯函数、hooks、组件独立行为
11
--------------------  Vitest / Jest
12

13
原则：越靠下越多、越快、越便宜；越靠上越少、越慢、越贵。
14
反模式：冰淇淋筒（E2E 特别多，跑得慢，维护成本高）

1
// Vitest 单元测试示例（Vue 组件）
2
import { describe, it, expect } from 'vitest';
3
import { mount } from '@vue/test-utils';
4
import Button from './Button.vue';
5

6
describe('Button', () => {
7
  it('渲染默认文本', () => {
8
    const wrapper = mount(Button);
9
    expect(wrapper.text()).toContain('按钮');
10
  });
11

12
  it('点击触发 click 事件', async () => {
13
    const wrapper = mount(Button);
14
    await wrapper.trigger('click');
15
    expect(wrapper.emitted('click')).toHaveLength(1);
16
  });
17

18
  it('disabled 时不响应点击', async () => {
19
    const wrapper = mount(Button, { props: { disabled: true } });
20
    await wrapper.trigger('click');
21
    expect(wrapper.emitted('click')).toBeUndefined();
22
  });
23
});
24

25
// Testing Library 核心理念：
26
// 从用户视角测试（找 role/text/label），不测实现细节
27
// 好处：重构不破坏测试，测试即文档

1
Playwright（微软）：
2
- 支持 Chromium / Firefox / WebKit 三大内核
3
- 多语言（JS/TS/Python/Java/.NET）
4
- 内置自动等待、trace viewer（回放调试）
5
- 并行执行、跨浏览器测试
6
- 支持移动端模拟
7

8
Cypress：
9
- 只支持 Chromium 系（近年也支持 Firefox/WebKit 实验）
10
- 时间旅行调试、快照
11
- 生态成熟、社区大
12
- 运行在浏览器内，某些场景受限（多标签页、iframe）
13

14
选型建议：
15
- 新项目 → Playwright（更现代、更快、功能全）
16
- 已有 Cypress 项目 → 继续用
17
- 需要跨浏览器测试 → Playwright

1
// Playwright 示例
2
import { test, expect } from '@playwright/test';
3

4
test('用户登录流程', async ({ page }) => {
5
  await page.goto('/login');
6
  await page.fill('[data-testid=username]', 'tom');
7
  await page.fill('[data-testid=password]', '123456');
8
  await page.click('button[type=submit]');
9
  await expect(page).toHaveURL('/dashboard');
10
  await expect(page.locator('.welcome')).toContainText('Tom');
11
});
12

13
// 关键实践：
14
// 1. 用 data-testid 而非 CSS 选择器（不受样式重构影响）
15
// 2. 网络拦截 mock 后端（page.route）
16
// 3. 只测关键用户流程（登录、下单、支付），别贪多
17
// 4. 测试数据独立，每次前后清理
18
// 5. CI 上并行执行，本地失败自动截图 + trace

1
分支策略（Trunk-Based Development 主流）：
2

3
main（生产）
4
  ↑ merge / PR
5
develop / feature/*
6
  ↑ commit
7

8
流水线阶段：
9

10
1. PR 阶段（自动）
11
   ├─ 依赖安装（利用 pnpm store 缓存）
12
   ├─ 类型检查（tsc --noEmit / vue-tsc）
13
   ├─ Lint（eslint + prettier --check）
14
   ├─ 单元测试（vitest run --coverage）
15
   ├─ 构建（vite build）
16
   ├─ 产物大小检查（bundlesize / size-limit）
17
   └─ Preview 部署（Vercel/Netlify 预览环境）
18

19
2. Merge 到 main（自动）
20
   ├─ 完整测试（含 E2E）
21
   ├─ 构建生产包
22
   ├─ 上传产物到 OSS / 镜像仓库
23
   ├─ 部署测试环境（自动）
24
   └─ 通知（企微/钉钉机器人）
25

26
3. 发版到生产（手动审批 or 打 tag 触发）
27
   ├─ 灰度发布（先 1% → 10% → 50% → 100%）
28
   ├─ CDN 刷新
29
   ├─ 健康检查（自动化冒烟测试）
30
   └─ 失败自动回滚（保留上一版本产物）
31

32
关键工具：
33
- GitHub Actions / GitLab CI / Jenkins
34
- 缓存：actions/cache 缓存 node_modules、pnpm store
35
- 制品仓库：Nexus / Verdaccio（私有 npm）
36
- 部署：Docker + K8s / 静态托管（OSS + CDN）/ Vercel

1
# .github/workflows/ci.yml 示例
2
name: CI
3
on: [push, pull_request]
4
jobs:
5
  build:
6
    runs-on: ubuntu-latest
7
    steps:
8
      - uses: actions/checkout@v4
9
      - uses: pnpm/action-setup@v3
10
        with: { version: 9 }
11
      - uses: actions/setup-node@v4
12
        with:
13
          node-version: 20
14
          cache: pnpm
15
      - run: pnpm install --frozen-lockfile
16
      - run: pnpm lint
17
      - run: pnpm typecheck
18
      - run: pnpm test --coverage
19
      - run: pnpm build
20
      - uses: actions/upload-artifact@v4
21
        with: { name: dist, path: dist }

1
灰度维度：
2
1. 用户维度：白名单 → 内测用户 → 部分用户 → 全量
3
2. 流量维度：1% → 10% → 50% → 100%
4
3. 地域维度：某城市 → 某区域 → 全国
5
4. 设备维度：某型号 → 某系统版本
6

7
实现方案：
8

9
方案 A：Nginx 层灰度（简单）
10
upstream backend {
11
  server new-version weight=1;   # 新版本 10%
12
  server old-version weight=9;   # 老版本 90%
13
}
14

15
方案 B：CDN + 版本目录
16
dist/
17
├── v1.0.0/index.html
18
├── v1.1.0/index.html
19
└── latest/ -> 软链切换
20
灰度逻辑：根据用户 ID hash 决定加载哪个版本
21

22
方案 C：客户端配置中心
23
- 前端启动时拉取灰度配置
24
- 后端根据用户特征返回是否命中新版本
25
- 命中则加载新 JS bundle，否则加载旧版
26

27
方案 D：特性开关（Feature Flag）
28
- 代码里所有新功能用 if (featureEnabled('new_ui')) 包裹
29
- 配置中心动态开关，无需发版
30
- 工具：LaunchDarkly、Unleash、自研
31

32
灰度回滚：
33
- 保留上一版本产物 3-7 天
34
- 监控错误率、崩溃率、业务指标
35
- 触发阈值自动回滚（如错误率 > 0.5%）

1
埋点分类：
2
1. 代码埋点（手动）：在业务代码里手动调 track()
3
   - 优点：精准、灵活
4
   - 缺点：侵入性高、易漏
5
2. 无埋点（全埋点）：SDK 自动采集所有点击/曝光
6
   - 优点：无侵入、可回溯
7
   - 缺点：数据量大、语义模糊
8
3. 可视化埋点：运营在页面上圈选元素配置事件
9
   - 优点：非技术人员可用
10
   - 缺点：需要平台支撑
11

12
主流 SDK 架构：
13
┌──────────────────────────────────────┐
14
│          前端埋点 SDK                 │
15
├──────────────────────────────────────┤
16
│ 采集层                                │
17
│ - 用户行为：click / scroll / route    │
18
│ - 性能指标：LCP / FCP / 长任务        │
19
│ - 错误：window.onerror / unhandled    │
20
│ - 接口：拦截 fetch/XHR                │
21
├──────────────────────────────────────┤
22
│ 上报层                                │
23
│ - navigator.sendBeacon（页面卸载）    │
24
│ - 批量合并 + 节流                     │
25
│ - requestIdleCallback 空闲上报        │
26
│ - 采样率控制                          │
27
├──────────────────────────────────────┤
28
│ 存储层（服务端）                       │
29
│ - Kafka 消息队列                      │
30
│ - ClickHouse / ES 存储                │
31
│ - 实时看板 + 离线分析                  │
32
└──────────────────────────────────────┘
33

34
关键实现：
35
- 页面访问：拦截 history.pushState / popstate / hashchange
36
- 元素曝光：IntersectionObserver
37
- 元素点击：事件委托 + 冒泡到 body 统一处理
38
- 页面停留：visibilitychange + beforeunload
39
- 用户轨迹：Session Replay（rrweb 录制 DOM 变化）