venturatravel/website-base

web-build-base - 网站构建基础Docker镜像

1. 镜像概述

web-build-base 是一个专为网站项目构建流程设计的基础Docker镜像，基于Alpine Linux发行版构建，集成了主流网站开发所需的构建工具链与依赖环境。该镜像旨在提供标准化、一致性的构建环境，消除因开发/部署环境差异导致的"在我这能跑"问题，适用于各类网站项目（前端、静态站点、需编译的后端网站等）的构建阶段。

2. 核心功能与特性

2.1 多工具集成

• 前端构建工具：Node.js (LTS版本)、npm、yarn、pnpm
• 版本控制：Git (支持代码拉取与子模块)
• 构建工具链：GCC、make、cmake (支持C/C++扩展编译)
• 静态站点生成器依赖：Python3、Ruby (可选，通过环境变量启用)

2.2 轻量级设计

• 基于Alpine Linux，基础镜像体积<100MB，集成工具后总大小<300MB，降低存储与传输成本。

2.3 环境一致性

• 预定义工具版本固定，避免因依赖版本差异导致的构建结果不一致。

2.4 构建缓存支持

• 内置缓存目录设计，支持挂载宿主机缓存卷，加速重复构建流程（如npm/yarn依赖缓存）。

2.5 可扩展性

• 支持通过apk add或自定义Dockerfile扩展工具链，满足特殊项目需求（如添加Java、Go等编译环境）。

3. 使用场景与适用范围

3.1 适用项目类型

• 前端项目：React、Vue、Angular、Svelte等框架的打包构建（npm run build）。
• 静态站点：Jekyll、Hugo、Hexo、Next.js等静态网站生成器的站点生成。
• 需编译的后端网站：基于Node.js、Deno的后端项目（含TypeScript编译步骤），或Go/Python后端的资源打包。

3.2 典型使用流程

• 本地开发：统一团队成员的构建环境，避免因本地工具版本差异导致的构建失败。
• CI/CD管道：作为Jenkins、GitHub Actions、GitLab CI等CI工具的构建容器，执行自动化构建流程。
• 构建服务器：在专用构建节点上部署，作为多项目共享的构建环境。

4. 使用方法与配置说明

4.1 镜像拉取

bash
# 拉取最新稳定版
docker pull web-build-base:latest

# 拉取特定版本（如Node.js 20.x分支）
docker pull web-build-base:node20

4.2 基本使用示例

4.2.1 本地项目构建（单命令执行）

将宿主机项目目录挂载至容器内，执行构建命令：

bash
# 假设项目目录为 ./my-web-project，构建命令为 npm run build
docker run -it --rm \
  -v $(pwd)/my-web-project:/app \  # 挂载项目目录至容器/app
  -v $(pwd)/build-cache:/tmp/cache \  # 挂载缓存目录（可选，加速依赖安装）
  -e NODE_ENV=production \  # 设置环境变量（如生产环境构建）
  web-build-base:latest \
  sh -c "cd /app && npm install && npm run build"  # 执行构建流程

4.2.2 docker-compose配置（适合多步骤构建）

创建docker-compose.yml：

yaml
version: '3.8'
services:
  build:
    image: web-build-base:latest
    volumes:
      - ./my-web-project:/app:rw  # 项目目录（读写权限）
      - build-cache:/tmp/cache:rw  # 持久化缓存卷
    environment:
      - NODE_VERSION=20.10.0  # 指定Node.js版本（可选，默认LTS）
      - BUILD_OUTPUT_DIR=/app/dist  # 构建输出目录（可选，默认/app/build）
    command: >
      sh -c "cd /app && 
             yarn install --cache-folder /tmp/cache/yarn && 
             yarn run build && 
             cp -r ${BUILD_OUTPUT_DIR} /app/built"  # 构建后复制输出到宿主机

volumes:
  build-cache:  # 声明缓存卷（持久化，避免每次重建缓存）

启动构建：

bash
docker-compose run --rm build

4.3 配置参数（环境变量）

4.4 扩展工具安装

如需添加镜像未预装的工具（如Go编译器），可通过Dockerfile基于本镜像构建自定义镜像：

dockerfile
# 自定义镜像 Dockerfile
FROM web-build-base:latest

# 安装Go 1.21（示例）
RUN apk add --no-cache go=1.21.5-r0 && \
    go version  # 验证安装

# 设置Go环境变量
ENV GOPATH=/go \
    PATH=$PATH:/go/bin

构建自定义镜像：

bash
docker build -t my-custom-web-build .

5. 注意事项

• 缓存卷挂载：推荐挂载/tmp/cache至宿主机目录或命名卷，避免重复下载依赖（如node_modules），提升构建效率。
• 权限问题：容器内默认使用root用户，如宿主机项目目录权限严格，可通过-u $(id -u):$(id -g)指定用户ID，避免文件权限冲突。
• 版本锁定：生产环境建议使用具体版本标签（如node20）而非latest，确保构建环境稳定性。