09 工程化与构建
  ├─ 前置：03 JavaScript（模块）、04 TypeScript（编译）
  ├─ 紧接：13 测试（CI 门禁）、10 网络（缓存与压缩）
  ├─ 交叉：11 性能（包体与加载）、12 安全（供应链）
  └─ 长期：17 架构（Monorepo 与平台化）

// ESM：导出的是「绑定」，不是值拷贝
export let count = 0;
export function inc() { count += 1; }

// 导入方看到的是实时值（只读）
import { count, inc } from './counter.js';
inc();
console.log(count); // 1

// CJS：导出的是对象快照，解构后就固定了
let count = 0;
module.exports = { get count() { return count; }, inc: () => { count += 1; } };

{
  "dependencies": {
    "react": "^18.3.1"
  },
  "devDependencies": {
    "vite": "^5.4.0"
  },
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview"
  }
}

/**
 * 构建配置的四个核心关注点：
 * 1) 入口与输出   2) 路径别名   3) 代理   4) 分包
 */
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'node:path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: { '@': path.resolve(__dirname, 'src') },
  },
  server: {
    port: 5173,
    proxy: {
      // 开发期代理，避免本地跨域
      '/api': { target: 'http://localhost:8080', changeOrigin: true },
    },
  },
  build: {
    target: 'es2020',          // 决定语法降级程度
    sourcemap: true,           // 线上排错必需（可用 hidden 模式）
    assetsInlineLimit: 4096,   // 小于 4KB 的资源内联为 base64
    rollupOptions: {
      output: {
        // 把变化频率低的第三方库单独拆出，利于长期缓存
        manualChunks: {
          react: ['react', 'react-dom'],
        },
      },
    },
  },
});

# .env.production
VITE_API_BASE=https://api.example.com

// 只有 VITE_ 前缀的变量会注入客户端
console.log(import.meta.env.VITE_API_BASE);

// ❌ 不要在客户端读取密钥：变量会被打进产物，人人可见

// 小于阈值 → base64 内联；否则 → 独立文件 + hash 文件名
import logo from './logo.svg';           // 返回 URL
import data from './config.json';        // 默认解析为对象
import Worker from './worker?worker';    // Vite 特有：以 Worker 方式加载

// 显式指定处理方式
import raw from './note.md?raw';         // 作为字符串
import url from './big.png?url';         // 强制返回 URL

dist/
├─ index.html                 # 入口，含 <script type="module" src="/assets/index-a1b2.js">
├─ assets/
│  ├─ index-a1b2.js           # 业务代码
│  ├─ react-c3d4.js           # 手动拆出的 vendor
│  ├─ OrderList-e5f6.js       # 路由懒加载 chunk
│  └─ index-g7h8.css
└─ favicon.ico

① resolve   把 import 说明符解析为绝对路径（含 alias、exports、扩展名）
② load      读取文件内容（磁盘/网络/缓存）
③ transform 转译（TS/JSX/Sass/图片），产出 JS 与 sourcemap
④ parse     生成 AST，收集 import/export，构建模块图
⑤ bundle    按图拼接作用域（scope hoisting）或包装为模块函数
⑥ chunk     按入口/动态导入/策略切分，计算 hash
⑦ emit      压缩、写盘、生成 manifest 与 HTML 注入

// ❌ 副作用导入：整个包都会被打进来
import _ from 'lodash';
_.debounce(fn, 300);

// ✅ 按需导入
import debounce from 'lodash/debounce';

// ✅ 更好的做法：换成 ESM 友好、可摇树的库
import { debounce } from 'es-toolkit';

// 库作者的 sideEffects：告诉打包器哪些文件不能删
{
  "sideEffects": ["*.css", "./src/polyfill.js"]
}

// 1) 路由级：最常用
const Detail = lazy(() => import('./pages/Detail'));

// 2) 交互级：点击后才需要
button.onclick = async () => {
  const { openEditor } = await import('./editor');
  openEditor();
};

// 3) 条件级：大模块按特性加载
if (features.charts) {
  const { renderChart } = await import('./charts');
  renderChart(el);
}

// 4) 依赖级：把稳定的大库单独拆出
// build.rollupOptions.output.manualChunks

<!-- 关键资源提前发现 -->
<link rel="modulepreload" href="/assets/react-c3d4.js" />
<link rel="preload" as="image" href="/hero.webp" fetchpriority="high" />
<link rel="prefetch" href="/assets/Detail-e5f6.js" />

// .browserslistrc：决定语法降级与 polyfill 范围
> 0.5%
last 2 versions
not dead
not op_mini all

// 语法降级（esbuild/swc/babel）≠ API 补齐（polyfill）
// 可选链能被降级；Promise.allSettled 需要 polyfill
import 'core-js/actual/promise/all-settled';

/* CSS Modules：类名在构建时被哈希，天然隔离 */
.title { color: red; }

import styles from './card.module.css';
// styles.title → '_title_a1b2c'

repo/
├─ apps/
│  ├─ web/          # 用户端
│  └─ admin/        # 管理端
├─ packages/
│  ├─ ui/           # 组件库
│  ├─ utils/        # 工具
│  └─ config/       # 共享配置（eslint/tsconfig/vite preset）
├─ pnpm-workspace.yaml
└─ turbo.json

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

// turbo.json：声明任务依赖与缓存，避免重复构建
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": { "dependsOn": ["build"] }
  }
}

// 内容 hash：内容不变 → 文件名不变 → 缓存长期有效
output: {
  entryFileNames: 'assets/[name]-[hash].js',
  chunkFileNames: 'assets/[name]-[hash].js',
  assetFileNames: 'assets/[name]-[hash][extname]',
}

# 找出重复版本（pnpm）
pnpm why react
pnpm list react --depth 10

# npm
npm ls react

{
  "pnpm": {
    "overrides": {
      "react": "18.3.1",
      "react-dom": "18.3.1"
    }
  }
}

开发模式（Vite）
浏览器请求 /src/main.tsx
  → 服务端按需转译「单个文件」（esbuild，毫秒级）
  → 以 ESM 形式返回
  → 浏览器自己处理 import（原生 ESM）
不打包整个应用 → 冷启动与 HMR 都只处理改动链路

生产模式（Vite）
Rollup 全量打包 → 更适合优化产物（摇树、分包、压缩）

/**
 * 一个最小插件：在产物里注入构建信息。
 * 插件本质是「在构建生命周期的特定钩子上做事情」。
 */
function buildInfoPlugin() {
  return {
    name: 'build-info',
    transform(code, id) {
      if (!id.endsWith('.ts')) return null;
      return null; // 不改代码
    },
    generateBundle(_options, bundle) {
      for (const file of Object.values(bundle)) {
        if (file.type === 'chunk' && file.isEntry) {
          file.code = `/* built at ${new Date().toISOString()} */\n${file.code}`;
        }
      }
    },
  };
}

# 1) 时间花在哪
DEBUG=vite:* vite build
# 或 webpack --profile + speed-measure-webpack-plugin

# 2) 体积花在哪
npx vite-bundle-visualizer

# 3) 哪个插件最慢
--debug 查看插件耗时

{
  "name": "my-ui",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./styles.css": "./dist/styles.css"
  },
  "sideEffects": ["*.css"]
}

# .github/workflows/ci.yml（示意）
jobs:
  build:
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - run: pnpm install --frozen-lockfile   # 锁文件不一致直接失败
      - run: pnpm lint
      - run: pnpm typecheck
      - run: pnpm test -- --coverage
      - run: pnpm build
      - run: pnpm size-limit                   # 包体预算门禁

开发者机器 → 上传输入 hash → 远程缓存命中 → 直接下载产物（秒级）
                          ↘ 未命中 → 分布式构建 → 回传缓存

<!-- SRI：CDN 资源被替换时浏览器拒绝执行 -->
<script src="https://cdn.example.com/lib.js"
        integrity="sha384-xxxx" crossorigin="anonymous"></script>

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json", ".env.production"],
      "outputs": ["dist/**"],
      "env": ["NODE_ENV", "API_BASE"]
    }
  }
}

冷构建 10–15 分钟 → 本地增量 1–2 分钟 → 远程命中 30–90 秒
命中率从 0 到 70% 的收益，通常大于把单步工具换快一倍

packages/config/
├─ eslint/         # 统一规则
├─ tsconfig/       # 统一编译选项
├─ vite-preset/    # 统一构建预设
└─ changelog.md    # 升级说明

- 构建耗时分布：babel-loader 55%，terser 20%，其余 25%
- 包体构成：组件库全量 600KB、moment 300KB、重复 lodash 2 份
- 首屏 chunk：包含所有页面代码（无路由分割）

{
  "size-limit": [
    { "path": "dist/assets/index-*.js", "limit": "200 kB" },
    { "path": "dist/assets/*.css", "limit": "60 kB" }
  ]
}

/**
 * 极简打包器：只处理相对路径与 ESM 的 import/export 语法子集。
 * @param {string} entry 入口绝对路径
 * @returns {string} 可执行的 bundle 代码
 */
function createBundle(entry) {
  const fs = require('fs');
  const path = require('path');
  /** @type {Map<string, {code: string, deps: string[]}>} */
  const modules = new Map();

  /** 递归收集依赖，返回模块 ID */
  const build = (file) => {
    if (modules.has(file)) return modules.get(file).id;
    const code = fs.readFileSync(file, 'utf8');
    const deps = [...code.matchAll(/from\s+['"](\.[^'"]+)['"]/g)].map((m) =>
      path.resolve(path.dirname(file), m[1])
    );
    const id = modules.size;
    modules.set(file, { id, code, deps });
    deps.forEach(build);
    return id;
  };

  build(entry);

  /** 把 import 改写成 require，导出挂到 module.exports */
  const wrap = (mod) => {
    const body = mod.code
      .replace(/import\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g, (_, name, spec) => {
        const dep = path.resolve(path.dirname([...modules.keys()][mod.id]), spec);
        return `const ${name} = require(${modules.get(dep).id})`;
      })
      .replace(/export\s+default\s+/g, 'module.exports = ')
      .replace(/export\s+(const|function|class)\s+(\w+)/g, '$1 $2; module.exports.$2 = $2;');
    return `${mod.id}: function(module, exports, require) {\n${body}\n}`;
  };

  return `(function(modules){
  const cache = {};
  function require(id) {
    if (cache[id]) return cache[id].exports;
    const module = { exports: {} };
    cache[id] = module;
    modules[id](module, module.exports, require);
    return module.exports;
  }
  require(0);
})({${[...modules.values()].map(wrap).join(',\n')}});`;
}

/**
 * 构建结束后输出 manifest，供服务端模板或预加载使用。
 * @returns {{name: string, generateBundle(options: object, bundle: object): void}}
 */
function manifestPlugin() {
  return {
    name: 'emit-manifest',
    generateBundle(_options, bundle) {
      /** @type {Record<string, {file: string, isEntry: boolean, imports: string[]}>} */
      const manifest = {};
      Object.values(bundle).forEach((chunk) => {
        if (chunk.type !== 'chunk') return;
        manifest[chunk.name] = {
          file: chunk.fileName,
          isEntry: chunk.isEntry,
          imports: chunk.imports,
        };
      });
      this.emitFile({
        type: 'asset',
        fileName: 'manifest.json',
        source: JSON.stringify(manifest, null, 2),
      });
    },
  };
}