构建缓存与加速：Bazel、Nx、Turborepo

Cache Key = Hash(
    源文件内容,
    传递依赖的输出哈希,
    构建工具版本,
    构建配置（compiler flags, env vars）,
    平台信息（OS, arch）
)

# WORKSPACE - 定义外部依赖和工具链
workspace(name = "my_monorepo")

# 加载 rules_nodejs 用于 Node.js 项目
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "build_bazel_rules_nodejs",
    sha256 = "6b3245ce8d3b4e1e44b3bac5e81b3e4a9d52e72c4f4c3e4a1b1c2d3e4f5a6b7c",
    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/6.0.0/rules_nodejs-6.0.0.tar.gz"],
)

load("@build_bazel_rules_nodejs//:index.bzl", "npm_install")

npm_install(
    name = "npm",
    package_json = "//:package.json",
    package_lock_json = "//:package-lock.json",
)

# 配置远程缓存
http_archive(
    name = "bazel_remote_cache",
    urls = ["https://github.com/buchgr/bazel-remote/releases/download/v2.4.0/bazel-remote-v2.4.0.tar.gz"],
)

# libs/utils/BUILD - 工具库构建定义
load("@npm//:defs.bzl", "npm_link_all_packages")
load("@build_bazel_rules_nodejs//:index.bzl", "ts_project", "npm_package")

# TypeScript 编译目标
ts_project(
    name = "utils",
    srcs = glob(["src/**/*.ts"]),
    tsconfig = "tsconfig.json",
    deps = [
        "//libs/types:types",
    ],
    visibility = ["//visibility:public"],
)

# 测试目标
ts_project(
    name = "utils_test",
    testonly = True,
    srcs = glob(["test/**/*.spec.ts"]),
    tsconfig = "tsconfig.json",
    deps = [
        ":utils",
        "@npm//jest",
        "@npm//@types/jest",
    ],
)

# npm 包发布目标
npm_package(
    name = "utils_pkg",
    srcs = [":utils"],
    package_name = "@myorg/utils",
    visibility = ["//visibility:public"],
)

# apps/web-app/BUILD - Web 应用构建定义
load("@build_bazel_rules_nodejs//:index.bzl", "ts_project")

ts_project(
    name = "web-app",
    srcs = glob(["src/**/*.ts", "src/**/*.tsx"]),
    tsconfig = "tsconfig.json",
    deps = [
        "//libs/utils:utils",
        "//libs/ui-components:ui-components",
        "@npm//react",
        "@npm//react-dom",
    ],
)

# 启动 Bazel Remote Cache 服务
docker run -d \
  --name bazel-remote-cache \
  -p 9092:9092 \
  -v /data/bazel-cache:/data \
  buchgr/bazel-remote:v2.4.0 \
  --dir /data \
  --max_size 50 \
  --port 9092

# .bazelrc - Bazel 配置文件
# 远程缓存配置
build --remote_cache=grpc://cache.example.com:9092
build --remote_upload_local_results=true

# 构建优化
build --jobs=auto
build --experimental_repository_cache_hardlinks
build --disk_cache=/home/user/.bazel/cache

# 沙箱配置（确保构建隔离）
build --spawn_strategy=standalone
build --strategy=TypeScriptCompile=standalone

# 平台配置
build --host_platform=@build_bazel_rules_nodejs//platforms:node18_linux_amd64

// nx.json - Nx 工作区配置
{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "affected": {
    "defaultBase": "main"
  },
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": {
        "cacheableOperations": ["build", "test", "lint", "e2e"],
        "parallel": 3
      }
    },
    "cloud": {
      "runner": "nx-cloud",
      "options": {
        "accessToken": "NX_CLOUD_ACCESS_TOKEN",
        "cacheableOperations": ["build", "test", "lint", "e2e"],
        "parallel": 4,
        "distribution": {
          "strategy": "dynamic",
          "targets": ["build", "test"]
        }
      }
    }
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["default", "^production"]
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"]
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/**/*.test.ts",
      "!{projectRoot}/tsconfig.spec.json"
    ],
    "sharedGlobals": [
      "{workspaceRoot}/tsconfig.base.json",
      "{workspaceRoot}/nx.json",
      "{workspaceRoot}/package-lock.json"
    ]
  }
}

// apps/web-app/project.json
{
  "name": "web-app",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "apps/web-app/src",
  "projectType": "application",
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/web-app",
        "index": "apps/web-app/src/index.html",
        "baseHref": "/",
        "main": "apps/web-app/src/main.tsx",
        "tsConfig": "apps/web-app/tsconfig.app.json",
        "assets": ["apps/web-app/src/favicon.ico", "apps/web-app/src/assets"],
        "styles": ["apps/web-app/src/styles.css"]
      },
      "configurations": {
        "production": {
          "optimization": true,
          "outputHashing": "all",
          "sourceMap": false,
          "namedChunks": false,
          "extractLicenses": true,
          "vendorChunk": false
        }
      }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "outputs": ["{workspaceRoot}/coverage/apps/web-app"],
      "options": {
        "jestConfig": "apps/web-app/jest.config.ts",
        "passWithNoTests": true
      }
    },
    "lint": {
      "executor": "@nx/linter:eslint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": ["apps/web-app/**/*.{ts,tsx,js,jsx}"]
      }
    }
  },
  "tags": ["type:app", "scope:web"]
}

#!/bin/bash
# ci-pipeline.sh - Nx 增量构建流水线

# 1. 检测受影响的项目（基于 PR 的变更范围）
AFFECTED_APPS=$(npx nx affected:apps --base=origin/main --head=HEAD)
AFFECTED_LIBS=$(npx nx affected:libs --base=origin/main --head=HEAD)

echo "Affected apps: $AFFECTED_APPS"
echo "Affected libs: $AFFECTED_LIBS"

# 2. 只构建和测试受影响的项目
npx nx affected:build --base=origin/main --head=HEAD --configuration=production
npx nx affected:test --base=origin/main --head=HEAD
npx nx affected:lint --base=origin/main --head=HEAD

# 3. 查看任务依赖图（可视化调试）
npx nx graph --affected --base=origin/main --head=HEAD

# 4. 分布式任务执行（Nx Cloud）
# 在 CI 中启用分布式执行，将任务分发到多台机器
npx nx affected:build --distribute-on="3" --configuration=production

# .github/workflows/nx-cloud-ci.yml
name: Nx Cloud CI

on:
  push:
    branches: [main]
  pull_request:

env:
  NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}

jobs:
  main:
    name: Nx Cloud - Main Job
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Derive SHAs for Nx Cloud
        uses: nrwl/nx-set-shas@v4

      - name: Run affected tasks with distribution
        run: npx nx affected --targets=lint,test,build --parallel=3

  agents:
    name: Nx Cloud - Agent
    runs-on: ubuntu-latest
    strategy:
      matrix:
        agent: [1, 2, 3]
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Start Nx Agent
        run: npx nx-cloud start-agent
        env:
          NX_AGENT_NAME: agent-${{ matrix.agent }}

// turbo.json - Turborepo 管道配置
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["package-lock.json", "tsconfig.base.json"],
  "globalEnv": ["NODE_ENV"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "outputMode": "new-only"
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts", "jest.config.*"]
    },
    "lint": {
      "outputs": [],
      "inputs": ["src/**/*.tsx", "src/**/*.ts", ".eslintrc.*"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "clean": {
      "cache": false
    }
  }
}

# Turborepo 远程缓存 - 自托管
# 使用 S3 作为后端存储

# 1. 启动自托管远程缓存服务器
docker run -d \
  --name turbo-remote-cache \
  -p 3000:3000 \
  -e STORAGE_TYPE=s3 \
  -e S3_BUCKET=turborepo-cache \
  -e S3_REGION=us-east-1 \
  -e AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID} \
  -e AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY} \
  -e TURBO_TOKEN=${TURBO_TOKEN} \
  -e TURBO_TEAM=my-team \
  duke0x/turborepo-remote-cache:latest

# 2. 配置客户端连接远程缓存
# 在 CI 环境中设置环境变量
export TURBO_API="https://cache.example.com"
export TURBO_TOKEN="${TURBO_CACHE_TOKEN}"
export TURBO_TEAM="my-team"

# 3. 执行构建（自动使用远程缓存）
npx turbo build --filter=web-app

my-monorepo/
├── turbo.json
├── package.json
├── package-lock.json
├── apps/
│   ├── web-app/
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── src/
│   └── admin-app/
│       ├── package.json
│       ├── tsconfig.json
│       └── src/
├── packages/
│   ├── ui-components/
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── src/
│   ├── utils/
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── src/
│   └── api-client/
│       ├── package.json
│       ├── tsconfig.json
│       └── src/
└── tools/
    └── scripts/

# .github/workflows/turbo-ci.yml
name: Turborepo CI

on:
  push:
    branches: [main]
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  TURBO_API: ${{ vars.TURBO_API }}
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}

jobs:
  build:
    name: Build & Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # Turborepo 需要至少 2 个 commit 来计算 diff

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Lint
        run: npx turbo lint

      - name: Build
        run: npx turbo build

      - name: Test
        run: npx turbo test

      - name: Cache miss analysis
        if: always()
        run: |
          # Turborepo 输出缓存命中统计
          npx turbo run build --dry-run --filter=...[HEAD^1] 2>&1 | grep -E "(FULL TURBO|CACHE MISS)" || true

// turbo.json - 精确的输入定义
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "inputs": [
        "src/**/*.ts",
        "src/**/*.tsx",
        "package.json",
        "tsconfig.json",
        ".babelrc",
        "webpack.config.*"
      ]
    }
  }
}

// nx.json - 区分 production 和 default 输入
{
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/**/*.test.ts",
      "!{projectRoot}/**/*.stories.ts",
      "!{projectRoot}/tsconfig.spec.json",
      "!{projectRoot}/.eslintrc.json"
    ]
  }
}

# Bazel 缓存清理
bazel clean --expunge          # 清理所有本地缓存
bazel clean                     # 清理输出目录，保留外部依赖

# Nx 缓存清理
npx nx reset                    # 清理所有本地缓存
npx nx clear-cache              # 清理计算缓存

# Turborepo 缓存清理
rm -rf .turbo                   # 清理本地缓存
npx turbo build --force         # 忽略缓存强制构建

# 远程缓存清理（按需）
# Bazel Remote Cache
curl -X DELETE "http://cache.example.com:9092/cache?action=clear"

# Turborepo Remote Cache (S3)
aws s3 rm s3://turborepo-cache/ --recursive

#!/bin/bash
# verify-cache-consistency.sh - 验证缓存一致性

# 执行两次构建，对比结果
echo "=== First build (cold cache) ==="
npx turbo build --force > build1.log 2>&1

echo "=== Second build (warm cache) ==="
npx turbo build > build2.log 2>&1

# 对比两次构建的产物哈希
echo "=== Comparing outputs ==="
find dist -type f -exec sha256sum {} \; | sort > checksums1.txt
npx turbo build --force > /dev/null 2>&1
find dist -type f -exec sha256sum {} \; | sort > checksums2.txt

if diff checksums1.txt checksums2.txt > /dev/null; then
  echo "PASS: Cache is consistent - cached outputs match fresh build"
else
  echo "FAIL: Cache inconsistency detected!"
  diff checksums1.txt checksums2.txt
  exit 1
fi

# .github/workflows/optimized-cache-ci.yml
name: Optimized Cache CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      # Turborepo 本地缓存持久化
      - name: Cache Turborepo local cache
        uses: actions/cache@v4
        with:
          path: .turbo
          key: turbo-${{ runner.os }}-${{ github.sha }}
          restore-keys: |
            turbo-${{ runner.os }}-

      # Nx 本地缓存持久化
      - name: Cache Nx local cache
        if: false  # 使用 Nx Cloud 时不需要
        uses: actions/cache@v4
        with:
          path: node_modules/.cache/nx
          key: nx-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-${{ github.sha }}
          restore-keys: |
            nx-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-

      - run: npm ci

      - name: Build with remote cache
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
        run: npx turbo build test lint

# Nx Cloud 提供内置的效果分析
npx nx-cloud record -- npx turbo build

# 查看缓存命中统计
npx nx-cloud stats --last-7-days

# 输出示例：
# ┌─────────────────────────────────────────┐
# │ Nx Cloud Statistics (Last 7 Days)       │
# ├─────────────────────────────────────────┤
# │ Total Tasks:        12,450              │
# │ Cache Hits:         9,830 (78.9%)       │
# │ Cache Misses:       2,620 (21.1%)       │
# │ Avg Full Build:     8m 32s              │
# │ Avg Cached Build:   1m 15s              │
# │ Time Saved:         1,245 hours         │
# │ Compute Saved:      78.9%               │
# └─────────────────────────────────────────┘

# Turborepo dry-run 分析缓存命中
npx turbo run build test lint --dry-run --filter=...[HEAD^1]

# 输出示例：
# ┌──────────────────┬──────────┬─────────────┐
# │ Task             │ Status   │ Duration    │
# ├──────────────────┼──────────┼─────────────┤
# │ utils#build      │ FULL TURBO │ <1ms      │
# │ ui#build         │ FULL TURBO │ <1ms      │
# │ api-client#build │ CACHE MISS │ 45s       │
# │ web-app#build    │ CACHE MISS │ 2m 30s    │
# │ web-app#test     │ CACHE MISS │ 1m 15s    │
# └──────────────────┴──────────┴─────────────┘
# 2 cached, 3 executed
# Total: 4m 30s (vs 12m 45s full build = 64.7% faster)