civiform/formatter

CiviForm 代码自动格式化依赖镜像

镜像概述和主要用途

概述

该Docker镜像为CiviForm代码库提供了自动格式化所需的完整依赖环境，集成了代码格式化工具及其运行时依赖，旨在简化开发流程并确保团队代码风格的一致性。

主要用途

• 支持CiviForm开发团队在本地开发环境中执行代码自动格式化
• 作为CI/CD流水线的标准化组件，实现代码提交前的自动格式化检查与修复
• 提供统一的格式化工具链，减少因本地环境差异导致的代码风格不一致问题

核心功能和特性

• 全量依赖集成：包含CiviForm项目所需的主流代码格式化工具（如Prettier、ESLint、Checkstyle、Black等，具体工具根据项目技术栈适配）及对应运行时环境（Node.js、Java JRE、Python等）
• 版本兼容性保障：内置依赖版本与CiviForm项目官方工具链版本严格匹配，避免版本冲突
• 预配置规则：集成CiviForm项目标准格式化规则，开箱即可使用，无需额外配置
• 轻量级设计：基于Alpine或slim基础镜像构建，最小化镜像体积（约200-500MB，视依赖复杂度）
• 多语言支持：覆盖CiviForm项目涉及的所有编程语言（Java、TypeScript、Python等）的格式化需求

使用场景和适用范围

使用场景

• 本地开发：开发人员通过容器化工具链执行代码格式化，避免本地环境配置繁琐
• CI/CD集成：在GitHub Actions、GitLab CI等流水线中自动触发格式化检查，确保提交代码符合规范
• 开发环境标准化：作为开发容器（如VS Code Dev Containers）的基础镜像，统一团队开发环境

适用范围

• CiviForm核心开发团队成员
• 参与CiviForm项目贡献的第三方开发者
• CiviForm项目的自动化构建与测试流程

详细使用方法和配置说明

前置条件

• Docker Engine 20.10+ 或 Docker Desktop
• 网络环境可访问镜像仓库（公网或私有仓库）

镜像拉取

bash
# 示例：从Docker Hub拉取最新版本
docker pull civiform/civiform-autoformat-deps:latest

# 示例：拉取指定版本（推荐生产环境使用固定版本）
docker pull civiform/civiform-autoformat-deps:v1.2.0

基础使用命令

1. 本地代码格式化

挂载本地代码目录至容器，执行格式化命令：

bash
docker run --rm \
  -v $(pwd):/app \  # 挂载本地代码目录到容器工作区
  -w /app \          # 设置容器工作目录
  civiform/civiform-autoformat-deps:latest \
  prettier --write . && eslint --fix .  # 执行格式化命令

2. 使用默认格式化命令

镜像内置默认格式化命令（可通过环境变量覆盖）：

bash
docker run --rm -v $(pwd):/app -w /app \
  civiform/civiform-autoformat-deps:latest

高级配置

环境变量

目录挂载

Docker部署方案示例

示例1：基础格式化命令

bash
# 格式化当前目录下的TypeScript/JavaScript文件
docker run --rm -v $(pwd):/app -w /app \
  -e FORMAT_CMD="prettier --write 'src/**/*.{ts,js,json}' && eslint --fix 'src/**/*.{ts,js}'" \
  civiform/civiform-autoformat-deps:v1.2.0

示例2：自定义配置文件

bash
# 使用本地自定义配置文件覆盖默认规则
docker run --rm \
  -v $(pwd):/app \
  -v $(pwd)/my-eslint-config:/app/.config \
  -w /app -e CONFIG_PATH="/app/.config" \
  civiform/civiform-autoformat-deps:v1.2.0

示例3：Docker Compose配置

创建docker-compose.yml：

yaml
version: '3.8'
services:
  code-format:
    image: civiform/civiform-autoformat-deps:v1.2.0
    volumes:
      - ./:/app                # 挂载项目代码
      - ./config:/app/.config  # 挂载自定义配置
    environment:
      - WORKDIR=/app
      - FORMAT_CMD="prettier --write . && eslint --fix . && black ."  # 多语言格式化
    command: ${FORMAT_CMD}

运行：

bash
docker-compose run --rm code-format

注意事项

• 生产环境建议使用固定镜像标签（如v1.2.0）而非latest，避免依赖变更风险
• 本地目录挂载时需确保当前用户对挂载目录有读写权限，可通过-u $(id -u):$(id -g)参数指定用户ID
• 自定义配置文件需与镜像内置工具版本兼容，建议参考CiviForm官方文档的配置规范
• 如需扩展工具链，可基于此镜像构建自定义镜像（通过FROM指令）并添加额外依赖