
Turborepo là một hệ thống build hiệu suất cao dành cho các monorepo JavaScript và TypeScript. Giá trị cốt lõi của nó nằm ở khả năng lập lịch tác vụ thông minh, bộ nhớ đệm dựa trên nội dung (content-addressable caching) và bộ nhớ đệm từ xa (remote caching). Hướng dẫn này trình bày chi tiết việc triển khai một thiết lập Turborepo mạnh mẽ, tập trung vào các bản dựng Docker được tối ưu hóa, bộ nhớ đệm từ xa được hỗ trợ bởi GCS và tăng tốc đáng kể pipeline CI.
Bộ nhớ đệm của Turborepo hoạt động dựa trên nguyên tắc địa chỉ hóa nội dung. Đối với bất kỳ tác vụ nào (ví dụ: build, test, lint), Turborepo sẽ tính toán một mã băm (hash) dựa trên:
inputs trong turbo.json.package.json của gói hiện tại và các dependency bắc cầu của nó.env trong turbo.json.turbo.json.Nếu một tác vụ có mã băm giống hệt đã được thực thi trước đó, Turborepo sẽ truy xuất kết quả được lưu trong bộ nhớ đệm thay vì chạy lại tác vụ. Kết quả này có thể được lưu trữ cục bộ hoặc trong bộ nhớ đệm từ xa.
Kiến trúc được tối ưu hóa của chúng tôi tích hợp Turborepo với Docker và Google Cloud Storage (GCS) để có một quy trình build có khả năng mở rộng, hiệu quả:
turbo prune: Tạo một tập hợp con tối thiểu của monorepo cần thiết để build một ứng dụng cụ thể, tối ưu hóa ngữ cảnh build của Docker.turbo prune và bộ nhớ đệm lớp của Docker để tạo ra các image gọn nhẹ, có thể tái tạo.| Tính năng | Ưu điểm | Nhược điểm |
|---|---|---|
turbo prune | Ngữ cảnh Docker tối thiểu, build nhanh hơn, image nhỏ hơn | Tăng độ phức tạp cho Dockerfile, yêu cầu định nghĩa turbo.json inputs cẩn thận |
| Multi-stage Docker | Image cuối cùng nhỏ hơn, cache lớp tốt hơn | Dockerfile phức tạp hơn, có khả năng phình to dependency trong thời gian build nếu không cẩn thận |
| GCS Remote Cache | Cache dùng chung, tính khả dụng cao, khả năng mở rộng, giảm thời gian CI | Chi phí GCS, độ phức tạp thiết lập ban đầu, độ trễ mạng khi cache miss |
| GitHub Actions | CI/CD tích hợp, hệ sinh thái tốt | Khóa nhà cung cấp (vendor lock-in), có thể bị giới hạn tốc độ (rate limits) trên các repo lớn |
turbo prune để Tối ưu hóa Docker Buildsturbo prune rất quan trọng đối với các bản dựng Docker. Nó tạo một thư mục mới chỉ chứa các gói và các dependency của chúng cần thiết để build một ứng dụng mục tiêu cụ thể trong monorepo. Điều này làm giảm đáng kể kích thước ngữ cảnh build của Docker, dẫn đến việc build image nhanh hơn và image nhỏ hơn.
Hãy xem xét một cấu trúc monorepo:
/
├── apps/
│ ├── web/
│ └── api/
├── packages/
│ ├── ui/
│ ├── utils/
│ └── db/
├── turbo.json
├── package.json
└── pnpm-lock.yaml
Để build apps/api, chúng ta chỉ cần apps/api, packages/utils và packages/db. turbo prune sẽ cô lập điều này.
turbo.jsonĐảm bảo turbo.json của bạn định nghĩa chính xác inputs và outputs cho các tác vụ. Điều này rất quan trọng để băm và cắt tỉa chính xác.
{
"$schema": "https://turbo.build/schema.json",
"pipeline": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", ".next/**", "build/**"],
"inputs": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.js", "src/**/*.jsx", "tsconfig.json", "package.json"]
},
"test": {
"dependsOn": ["^build"],
"outputs": [],
"inputs": ["src/**/*.test.ts", "src/**/*.test.tsx", "src/**/*.spec.ts", "src/**/*.spec.tsx"]
},
"lint": {
"outputs": []
},
"dev": {
"cache": false,
"persistent": true
}
}
}
turbo pruneĐây là một Dockerfile đa giai đoạn cho một ứng dụng api, tận dụng turbo prune.
# Stage 1: Build dependencies and application
FROM node:20-alpine AS builder
# Install pnpm globally
RUN corepack enable && corepack prepare pnpm@latest --activate
# Set working directory
WORKDIR /app
# Copy lockfile and package.json files first to leverage Docker cache
# This layer changes infrequently, maximizing cache hits
COPY pnpm-lock.yaml ./
COPY package.json ./
COPY turbo.json ./
# Copy only the pruned monorepo subset for the 'api' application
# This command is executed by the CI/CD pipeline or locally before `docker build`
# Example: `turbo prune --scope=api --docker`
# The output of `turbo prune` is expected in the './.pruned-build' directory
COPY .pruned-build/pnpm-workspace.yaml ./.pruned-build/
COPY .pruned-build/full/ ./.pruned-build/full/
COPY .pruned-build/json/ ./.pruned-build/json/
# Install dependencies using pnpm
# Use --frozen-lockfile to ensure reproducible builds
RUN pnpm install --frozen-lockfile --prod=false
# Copy the actual source code for the pruned packages
# This is crucial: `turbo prune` only copies package.json and lockfiles,
# not the source code itself. We copy it from the original context.
# The `full` directory contains symlinks to the original source.
# We need to copy the actual files.
# This assumes the Docker build context is the root of the monorepo.
COPY apps/api ./apps/api
COPY packages/db ./packages/db
COPY packages/utils ./packages/utils
# Build the 'api' application
# Turborepo will use its cache or build if necessary
RUN pnpm turbo run build --filter=api...
# Stage 2: Production image
FROM node:20-alpine AS runner
# Install pnpm globally (for production dependencies if needed, though often not)
RUN corepack enable && corepack prepare pnpm@latest --activate
WORKDIR /app
# Copy only production dependencies from the builder stage
# This ensures a minimal production image
COPY --from=builder /app/pnpm-lock.yaml ./
COPY --from=builder /app/package.json ./
COPY --from=builder /app/turbo.json ./
COPY --from=builder /app/.pruned-build/pnpm-workspace.yaml ./.pruned-build/
COPY --from=builder /app/.pruned-build/json/ ./.pruned-build/json/
# Install production dependencies
RUN pnpm install --prod --frozen-lockfile
# Copy the built application artifacts from the builder stage
# This includes `dist` directories for the API and its dependencies
COPY --from=builder /app/apps/api/dist ./apps/api/dist
COPY --from=builder /app/packages/db/dist ./packages/db/dist
COPY --from=builder /app/packages/utils/dist ./packages/utils/dist
# Expose port (if applicable)
EXPOSE 3000
# Define the command to run the application
CMD ["node", "apps/api/dist/index.js"]
Giải thích về turbo prune trong ngữ cảnh Docker:
turbo prune --scope=api --docker: Lệnh này, được thực thi trước docker build, tạo một thư mục .pruned-build tại thư mục gốc của monorepo.
pnpm-workspace.yaml: Được sao chép vào .pruned-build/pnpm-workspace.yaml.full/: Chứa các symlink đến các tệp package.json của tất cả các gói liên quan.json/: Chứa các tệp package.json của tất cả các gói liên quan, nhưng được làm phẳng.COPY .pruned-build/...: Chúng ta sao chép các tệp được tạo này vào image Docker.pnpm install: Với các tệp package.json đã được cắt tỉa và pnpm-lock.yaml, pnpm chỉ cài đặt các dependency cần thiết.COPY apps/api ./apps/api: Quan trọng là, turbo prune không sao chép các tệp nguồn. Bạn phải sao chép rõ ràng mã nguồn cho ứng dụng mục tiêu và các dependency trực tiếp của nó từ ngữ cảnh monorepo gốc. Đây là lý do tại sao lệnh docker build nên được chạy từ thư mục gốc của monorepo.pnpm turbo run build --filter=api...: Turborepo build ứng dụng api và các dependency thượng nguồn của nó.Turborepo hỗ trợ nhiều backend remote cache khác nhau. Đối với môi trường doanh nghiệp, một giải pháp tự lưu trữ sử dụng lưu trữ đám mây (GCS, S3) mang lại khả năng kiểm soát, khả năng mở rộng và hiệu quả chi phí.
gs://your-turborepo-cache-bucketStorage Object Admin hoặc Storage Object Creator và Storage Object Viewer.Turborepo sử dụng các biến môi trường để cấu hình remote caching.
# .env.local or CI environment variables
TURBO_REMOTE_CACHE_SIGNATURE_KEY="your_strong_secret_key_for_signing_cache_requests"
TURBO_REMOTE_CACHE_READ_ONLY="false" # Set to true for read-only environments
TURBO_REMOTE_CACHE_GCS_BUCKET="your-turborepo-cache-bucket"
TURBO_REMOTE_CACHE_GCS_SERVICE_ACCOUNT_KEY="path/to/your/gcs-service-account-key.json" # Or base64 encoded JSON
Lưu ý bảo mật quan trọng: Không bao giờ commit TURBO_REMOTE_CACHE_SIGNATURE_KEY hoặc TURBO_REMOTE_CACHE_GCS_SERVICE_ACCOUNT_KEY trực tiếp vào kho lưu trữ của bạn. Hãy sử dụng các biến môi trường, hệ thống quản lý bí mật (ví dụ: GitHub Secrets, GCP Secret Manager).
Đối với CI/CD, bạn thường sẽ mã hóa base64 khóa tài khoản dịch vụ JSON và lưu trữ nó dưới dạng bí mật.
# Example for GitHub Actions
echo "${{ secrets.GCP_SERVICE_ACCOUNT_KEY_BASE64 }}" | base64 --decode > gcs-key.json
export TURBO_REMOTE_CACHE_GCS_SERVICE_ACCOUNT_KEY=$(pwd)/gcs-key.json
Việc tích hợp các thành phần trên vào một quy trình GitHub Actions giúp giảm đáng kể thời gian build CI.
name: CI Build & Test
on:
push:
branches:
- main
pull_request:
branches:
- main
jobs:
build-api:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0 # Required for Turborepo to correctly detect changed files
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm' # Cache pnpm dependencies
- name: Install pnpm
run: corepack enable && corepack prepare pnpm@latest --activate
- name: Install monorepo dependencies
run: pnpm install --frozen-lockfile
- name: Configure Turborepo Remote Cache (GCS)
env:
TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
TURBO_REMOTE_CACHE_GCS_BUCKET: your-turborepo-cache-bucket
GCP_SERVICE_ACCOUNT_KEY_BASE64: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY_BASE64 }}
run: |
echo "${{ env.GCP_SERVICE_ACCOUNT_KEY_BASE64 }}" | base64 --decode > gcs-key.json
export TURBO_REMOTE_CACHE_GCS_SERVICE_ACCOUNT_KEY=$(pwd)/gcs-key.json
echo "TURBO_REMOTE_CACHE_GCS_SERVICE_ACCOUNT_KEY=$(pwd)/gcs-key.json" >> $GITHUB_ENV
echo "TURBO_REMOTE_CACHE_SIGNATURE_KEY=${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}" >> $GITHUB_ENV
echo "TURBO_REMOTE_CACHE_GCS_BUCKET=your-turborepo-cache-bucket" >> $GITHUB_ENV
- name: Build API application with Turborepo
run: pnpm turbo run build --filter=api...
- name: Run API tests with Turborepo
run: pnpm turbo run test --filter=api...
- name: Lint API application with Turborepo
run: pnpm turbo run lint --filter=api...
- name: Prune API for Docker build
run: pnpm turbo prune --scope=api --docker
- name: Build Docker image for API
run: docker build -t your-registry/api:${{ github.sha }} -f apps/api/Dockerfile .
- name: Push Docker image (example)
# Add Docker login steps here if pushing to a private registry
# run: docker push your-registry/api:${{ github.sha }}
run: echo "Docker image built: your-registry/api:${{ github.sha }}"
Các tối ưu hóa chính trong quy trình CI:
actions/checkout@v4 với fetch-depth: 0: Đảm bảo Turborepo có quyền truy cập vào toàn bộ lịch sử Git để phát hiện thay đổi và lưu vào bộ nhớ đệm chính xác.actions/setup-node@v4 với cache: 'pnpm': Lưu vào bộ nhớ đệm node_modules cho pnpm, giảm thời gian pnpm install trong các lần chạy tiếp theo.pnpm turbo run build --filter=api...: Turborepo xây dựng một cách thông minh chỉ ứng dụng api và các dependency của nó. Nếu có cache hit, bước này hoàn thành gần như ngay lập tức.pnpm turbo prune --scope=api --docker: Tạo ngữ cảnh build được tối ưu hóa cho Docker.docker build ... -f apps/api/Dockerfile .: Build image Docker. Vì turbo prune đã giảm ngữ cảnh và Dockerfile là đa giai đoạn, bước này nhanh hơn đáng kể.Cache Misses Mặc dù Không có Thay đổi Mã:
cache MISS ngay cả khi không có mã liên quan nào thay đổi.inputs hoặc outputs trong turbo.json. Nếu một tệp ảnh hưởng đến bản dựng không được liệt kê trong inputs, các thay đổi của nó sẽ không làm mất hiệu lực bộ nhớ đệm. Nếu outputs không được định nghĩa chính xác, Turborepo có thể không lưu trữ toàn bộ đầu ra.env được định nghĩa trong turbo.json thay đổi giữa các lần chạy, mã băm sẽ thay đổi.package.json hoặc pnpm-lock.yaml trong một dependency.fetch-depth trong actions/checkout quá nông, ngăn Turborepo phát hiện thay đổi chính xác.turbo.json inputs và outputs. Sử dụng git diff --name-only <commit-ish> để xác định các tệp đã thay đổi và đảm bảo chúng được bao phủ.fetch-depth: 0 trong actions/checkout.pnpm turbo run <task> --dry-run=json để kiểm tra mã băm và đầu vào được tính toán.turbo prune Không Bao gồm Các Tệp Cần Thiết:
turbo prune.turbo prune của lệnh --scope quá hẹp, hoặc biểu đồ dependency không được Turborepo hiểu đúng.COPY trong Dockerfile không đầy đủ, không sao chép tất cả các tệp nguồn cần thiết từ ngữ cảnh monorepo gốc.pnpm turbo graph --filter=api.... Đảm bảo tất cả các gói cần thiết được liệt kê..pruned-build sau khi chạy turbo prune.COPY trong Dockerfile của bạn, đảm bảo tất cả các thư mục nguồn cho ứng dụng mục tiêu và các dependency trực tiếp của nó được bao gồm. Hãy nhớ turbo prune chỉ xử lý package.json và lockfile, không phải mã nguồn.Lỗi Quyền GCS:
Storage Object Admin hoặc ít nhất Storage Object Creator và Storage Object Viewer cho tài khoản dịch vụ trên GCS bucket cụ thể. Đảm bảo đường dẫn TURBO_REMOTE_CACHE_GCS_SERVICE_ACCOUNT_KEY chính xác và tệp có thể đọc được.pnpm install Chậm trong Docker:
turbo prune, pnpm install mất nhiều thời gian trong Docker build.pnpm-lock.yaml hoặc package.json thường xuyên thay đổi, làm mất hiệu lực bộ nhớ đệm lớp Docker cho pnpm install.pnpm được sử dụng trong Dockerfile.pnpm-lock.yaml được commit và cập nhật.pnpm-lock.yaml, package.json và turbo.json trước, sau đó chạy pnpm install. Điều này tối đa hóa việc lưu vào bộ nhớ đệm lớp.pnpm dùng chung cho phát triển cục bộ, mặc dù điều này khó hơn trong CI. Bộ nhớ đệm actions/setup-node giúp ích trong CI.Cơ chế băm của Turborepo xem xét package.json của gói hiện tại và tất cả các dependency bắc cầu của nó. Nếu bất kỳ package.json nào trong chuỗi dependency thay đổi, hoặc nếu pnpm-lock.yaml (hoặc yarn.lock, package-lock.json) thay đổi, mã băm cho các tác vụ phụ thuộc vào các gói đó sẽ bị vô hiệu hóa, dẫn đến cache miss. Điều này đảm bảo tính đúng đắn.
Có. Turborepo hỗ trợ nhiều nhà cung cấp remote cache khác nhau. Ngoài GCS, nó hỗ trợ nguyên bản Vercel Remote Cache (cho các triển khai Vercel), AWS S3 và một endpoint HTTP chung. Đối với S3, bạn sẽ sử dụng TURBO_REMOTE_CACHE_S3_BUCKET, TURBO_REMOTE_CACHE_S3_REGION và thông tin xác thực AWS. Đối với một endpoint HTTP tùy chỉnh, bạn sẽ cấu hình TURBO_REMOTE_CACHE_URL.
fetch-depth: 0 đến hiệu suất và bảo mật CI là gì?fetch-depth: 0 hướng dẫn Git tìm nạp toàn bộ lịch sử của kho lưu trữ, không chỉ commit mới nhất.
Sử dụng cờ --dry-run với pnpm turbo run.
pnpm turbo run build --filter=api... --dry-run: Hiển thị các tác vụ nào sẽ chạy và tại sao (ví dụ: cache MISS, cache HIT).pnpm turbo run build --filter=api... --dry-run=json: Cung cấp đầu ra JSON chi tiết, bao gồm mã băm được tính toán cho mỗi tác vụ, đầu vào và đầu ra của nó. Điều này rất có giá trị để hiểu tại sao cache miss xảy ra.TURBO_LOG_LEVEL=debug để ghi nhật ký chi tiết.turbo prune và multi-stage builds. Có thể có vấn đề gì?.dockerignore của bạn. Đảm bảo nó loại trừ các tệp chỉ dành cho phát triển, .git, node_modules (ngoại trừ bước pnpm install) và các tạo phẩm build khác.runner trong ví dụ) chỉ sao chép các tạo phẩm đã build và các dependency sản xuất. Nếu bạn sao chép node_modules từ giai đoạn builder trực tiếp mà không cài đặt lại bằng --prod, bạn sẽ bao gồm các dependency phát triển.node:20-alpine thường gọn nhẹ. Tránh các image cơ sở lớn hơn như node:20 (dựa trên Debian) cho sản xuất.runner của bạn không chứa các trình biên dịch, linter hoặc các công cụ build khác từ giai đoạn builder. Dockerfile ví dụ giải quyết đúng vấn đề này bằng cách chỉ sao chép các thư mục dist cụ thể và cài đặt lại pnpm cho các dependency sản xuất.Bằng cách áp dụng tỉ mỉ các chiến lược này, các tổ chức có thể giảm đáng kể thời gian build CI, dẫn đến vòng phản hồi nhanh hơn, triển khai thường xuyên hơn và cải thiện năng suất của nhà phát triển.
Một nhóm đang gặp phải tình trạng thời gian build chậm hơn đáng kể so với dự kiến trong pipeline CI/CD của họ, mặc dù đã triển khai Turborepo với remote caching. Sau khi điều tra, họ phát hiện ra rằng nhiều task liên tục chạy lại thay vì hit cache. Đâu là nguyên nhân gốc rễ CÓ KHẢ NĂNG NHẤT, xét đến các thách thức kỹ thuật trong thực tế?
Làm sạch log AI CLI, tạo biểu thức cron, giải mã JWT và tính quyền chmod offline.

Hướng dẫn toàn diện về kiểm thử hồi quy hình ảnh Playwright ở quy mô lớn: docker baselines, pixelmatch & flaky ci shields với kiến trúc cấp độ sản xuất và các ví dụ mã.
Đọc tiếp
Đừng đưa trình biên dịch vào môi trường production. Cách sử dụng Docker multistage builds với uv và BuildKit caching cho FastAPI - từ 1,2 GB xuống dưới 100 MB, với thời gian CI rebuild nhanh chóng.
Đọc tiếp
Tăng tốc build Docker Python từ vài phút xuống vài giây bằng Astral uv, các target đa giai đoạn, BuildKit persistent cache mounts và các runtime image tinh gọn.
Đọc tiếp