Build Engineering

Optimizes build toolchains and monorepo setups using Vite/Webpack, Turborepo, and CI/CD to improve performance, code sharing, module federation, and develope...

Security Scan

The skill is an instruction-only build-engineering guide whose requested artifacts (none) and runtime instructions align with its stated purpose; it does not ask for credentials, installs, or unusual system access.

Purpose & Capability

Name and description match the SKILL.md content: diagnostics and configuration guidance for Vite/Webpack, pnpm/Turborepo monorepos, Module Federation, CI optimizations and code generation. There are no unrelated environment variables, binaries, or config paths requested.

Instruction Scope

SKILL.md contains actionable commands, configuration snippets, and CI examples (pnpm, npx, GitHub Actions YAML, module-federation config). The instructions stay on-topic (provide configs, ask diagnostic questions) and do not instruct reading arbitrary host files or exfiltrating data. Note: many snippets assume repository context and network access; if the agent is allowed to execute shell commands in a live environment, those actions could modify the repo or contact remote endpoints.

Install Mechanism

No install spec and no code files to install — instruction-only. This minimizes on-disk risk; nothing is downloaded or executed by the skill itself.

Credentials

The skill declares no required environment variables, credentials, or config paths. Examples reference CI runtime variables (e.g., ${{ github.sha }}) only as standard CI patterns; no secret access is requested by the skill itself.

Persistence & Privilege

always:false and default autonomous invocation are set. The skill does not request persistent presence or modify other skills/configs. Autonomous invocation is normal; combined with the lack of requested credentials and no install, this presents low additional risk.

Assessment

This skill is a textual best-practice guide for build systems and appears internally consistent. Before using it, consider: (1) If you allow the agent to run shell commands or apply the provided snippets, restrict that action to a safe sandbox or review changes in a PR — the snippets can modify your repo or trigger CI. (2) The skill does not request secrets, but applying CI optimizations or publishing packages will require your existing tokens/credentials; do not provide those to the skill itself. (3) For Module Federation or remote entries, ensure any remote endpoints you configure are trusted. If you want the agent to perform live operations (install packages, run builds, push commits), require explicit, audited consent and limit the agent's runtime permissions.

构建与工程化（Build Engineering）

解决构建慢、包体积大、多包协作混乱、CI 不稳定等工程问题，让团队把时间花在业务上而不是工具上。

触发场景

• 「构建太慢了」「热更新卡」「CI 跑 20 分钟」
• 「多个项目共享组件，怎么管理」「Monorepo 怎么搭」
• 「微前端怎么做」「模块联邦怎么配」
• 「bundle 分析完了，不知道怎么优化」
• 「代码生成」「自动化脚本」「工程规范落地」

---

执行流程

1. 先定位问题类型

用户描述	实际问题	第一步
「构建慢」「dev 启动慢」	构建性能	问：用 Vite 还是 Webpack？冷启动多久？热更新多久？
「多个项目共享代码」	代码共享架构	问：几个项目？是否需要独立发版？团队规模？
「微前端」「模块联邦」	运行时集成	问：是独立部署还是同仓库？需要共享状态吗？
「CI 太慢」「流水线不稳定」	CI/CD 优化	问：用什么 CI？哪个步骤最慢？有没有缓存？
「bundle 大」	产物优化	直接让用户跑分析工具，看报告再说

2. 构建性能优化

Vite 项目慢的常见原因和解法：

问题	诊断方式	解法
冷启动慢	看 vite --debug 输出	检查是否有大量 CommonJS 依赖需要预构建；用 optimizeDeps.include 预声明
热更新慢	改一个文件，看 HMR 耗时	检查是否有循环依赖；大型组件库按需引入
生产构建慢	vite build --profile	开启 build.rollupOptions.output.manualChunks 手动分包；关闭不需要的插件

Webpack 项目提速的优先级顺序：

1. 升级到 Webpack 5（持久化缓存 cache: { type: 'filesystem' }）
2. 缩小 loader 处理范围（include: path.resolve('src')，排除 node_modules）
3. 开启多线程（thread-loader 用于 babel/ts 编译）
4. 用 esbuild-loader 替换 babel-loader（速度提升 10-20x）
5. 考虑迁移到 Vite（新项目首选，存量项目评估迁移成本）

不要做的事：

• 不要为了"优化"随意升级 Webpack 大版本，破坏性变更多
• 不要在没有 profile 数据的情况下盲目加插件

3. Monorepo 架构决策

什么时候需要 Monorepo：

• 3 个以上项目共享组件/工具/类型
• 需要原子提交（一个 PR 同时改多个包）
• 团队需要统一的 lint/test/build 规范

什么时候不需要：

• 项目完全独立，没有共享代码
• 团队 < 3 人，管理成本大于收益

推荐方案（2025 年）：

pnpm workspace + Turborepo
├── apps/
│   ├── web/          # 主应用
│   └── admin/        # 管理后台
├── packages/
│   ├── ui/           # 共享组件库
│   ├── utils/        # 工具函数
│   ├── types/        # 共享类型
│   └── config/       # 共享配置（eslint���tsconfig、tailwind）
├── pnpm-workspace.yaml
└── turbo.json

Turborepo 关键配置：

// turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],  // 先构建依赖包
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "dev": {
      "cache": false,           // dev 不缓存
      "persistent": true
    }
  }
}

包之间的依赖声明：

// apps/web/package.json
{
  "dependencies": {
    "@myorg/ui": "workspace:*",
    "@myorg/utils": "workspace:*"
  }
}

4. 模块联邦（Module Federation）

适用场景： 多个独立部署的应用需要在运行时共享组件或逻辑（微前端）。

不适用场景： 同一仓库的多个包——用 Monorepo 就够了，不需要模块联邦。

Vite 模块联邦配置（@originjs/vite-plugin-federation）：

// 提供方（组件库应用）vite.config.ts
import federation from '@originjs/vite-plugin-federation'

export default {
  plugins: [
    federation({
      name: 'remote-app',
      filename: 'remoteEntry.js',
      exposes: {
        './Button': './src/components/Button.vue',
        './utils': './src/utils/index.ts',
      },
      shared: ['vue', 'pinia'],  // 共享依赖，避免重复加载
    })
  ],
  build: { target: 'esnext' }  // 模块联邦需要 esnext
}

// 消费方 vite.config.ts
export default {
  plugins: [
    federation({
      name: 'host-app',
      remotes: {
        'remote-app': 'http://localhost:5001/assets/remoteEntry.js',
      },
      shared: ['vue', 'pinia'],
    })
  ]
}

模块联邦的坑：

• 共享依赖版本必须兼容，否则会加载两份
• 类型不会自动共享，需要单独处理（发布 .d.ts 或用 @module-federation/typescript）
• 本地开发需要先构建提供方，或用 vite preview 模拟

5. CI/CD 优化

CI 慢的排查顺序：

1. 缓存命中率：node_modules、构建产物、测试结果是否有缓存？
2. 并行化：lint、test、build 能否并行跑？
3. 增量执行：只跑受影响的包（Turborepo --filter 或 affected）
4. 测试分片：大型测试套件拆分到多个 runner 并行

GitHub Actions 最佳实践：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v3
        with: { version: 9 }

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'          # 缓存 pnpm store

      - run: pnpm install --frozen-lockfile

      - name: Cache Turborepo
        uses: actions/cache@v4
        with:
          path: .turbo
          key: turbo-${{ github.sha }}
          restore-keys: turbo-   # 前缀匹配，复用历史缓存

      - run: pnpm turbo build test --filter='[HEAD^1]'  # 只跑有变更的包

6. 代码生成与自动化

值得自动化的场景：

• 从 OpenAPI/Swagger 生成 API 类型和请求函数（openapi-typescript + orval）
• 从设计 token 生成 CSS 变量和 Tailwind 配置（style-dictionary）
• 新功能脚手架（plop 或自定义 CLI）

OpenAPI 代码生成示例：

# 安装
pnpm add -D openapi-typescript orval

# 生成类型
npx openapi-typescript ./api/openapi.yaml -o ./src/types/api.d.ts

# orval 生成 React Query hooks
# orval.config.ts
export default {
  api: {
    input: './api/openapi.yaml',
    output: {
      mode: 'tags-split',
      target: './src/api',
      schemas: './src/types',
      client: 'react-query',
      override: {
        mutator: { path: './src/lib/axios.ts', name: 'customInstance' }
      }
    }
  }
}

新功能脚手架（plop）：

// plopfile.js
export default function (plop) {
  plop.setGenerator('component', {
    description: '创建新组件',
    prompts: [
      { type: 'input', name: 'name', message: '组件名称（PascalCase）' },
      { type: 'list', name: 'type', choices: ['ui', 'feature', 'page'] }
    ],
    actions: [
      { type: 'add', path: 'src/components/{{name}}/index.tsx', templateFile: 'plop-templates/component.hbs' },
      { type: 'add', path: 'src/components/{{name}}/{{name}}.test.tsx', templateFile: 'plop-templates/component.test.hbs' },
    ]
  })
}

---

输出模板

## 工程化方案

### 问题诊断
- 当前瓶颈：…（构建耗时 / CI 耗时 / 包管理问题）

### 方案
- 构建工具：Vite / Webpack 5 + 具体配置
- 包管理：pnpm workspace + Turborepo
- CI 优化：缓存策略 + 并行化 + 增量构建

### 关键配置
- turbo.json pipeline 设计
- CI 缓存 key 策略
- 代码生成工具链

### 预期收益
- 构建时间：X min → Y min
- CI 时间：X min → Y min