codacy-metrics-eslint Docker镜像文档

1. 镜像概述

codacy-metrics-eslint 是 Codacy 平台提供的 Docker 镜像，用于集成 ESLint 工具对 JavaScript/TypeScript 代码进行静态分析，生成标准化的代码质量指标（如错误数、警告数、代码复杂度等），并兼容 Codacy 平台的数据格式，支持代码质量持续监控与分析。

2. 核心功能和特性

• ESLint 深度集成：内置 ESLint 及常用规则集，支持执行代码语法检查、风格校验及最佳实践检测。
• 标准化指标生成：输出符合 Codacy 平台规范的代码质量指标（如 issue 数量、严重级别分布、规则违反统计等）。
• 自定义配置支持：允许挂载外部 ESLint 配置文件（.eslintrc、.eslintignore），适配项目个性化规则需求。
• 轻量级设计：基于 Alpine 基础镜像，精简依赖，减少容器体积，提升运行效率。
• CI/CD 兼容性：支持与主流 CI/CD 工具（Jenkins、GitHub Actions 等）集成，实现自动化代码质量检查。

3. 使用场景和适用范围

• Codacy 平台集成：作为 Codacy 代码质量分析流程的插件，为 JavaScript/TypeScript 项目提供 ESLint 检测数据。
• 自动化代码检查：在 CI/CD 流程中自动执行 ESLint 检查，提前发现代码风格或语法问题。
• 团队代码规范统一：通过标准化配置，确保团队内代码质量指标收集口径一致。
• 历史代码质量回溯：结合 Codacy 平台存储的历史数据，分析代码质量变化趋势。

4. 使用方法和配置说明

4.1 前提条件

• 已安装 Docker 环境（20.10+ 版本推荐）。
• （可选）Codacy 项目令牌（需在 Codacy 平台创建项目后获取，用于数据上报）。
• 项目中已准备 ESLint 配置文件（如无，将使用镜像内置默认规则）。

4.2 Docker 命令直接运行

基础用法（本地代码检查）

docker run --rm \
  -v $(pwd):/app \  # 挂载本地项目目录到容器内 /app
  codacy-metrics-eslint:latest \
  analyze /app  # 指定分析目录（容器内路径）

带自定义 ESLint 配置

docker run --rm \
  -v $(pwd):/app \
  -v $(pwd)/.eslintrc.js:/app/.eslintrc.js \  # 挂载自定义 ESLint 配置
  -v $(pwd)/.eslintignore:/app/.eslintignore \  # 挂载忽略文件配置
  codacy-metrics-eslint:latest \
  analyze /app

集成 Codacy 平台（上报指标）

docker run --rm \
  -v $(pwd):/app \
  -e CODACY_PROJECT_TOKEN=your-project-token \  # Codacy 项目令牌
  -e CODACY_API_URL=[***] \  # Codacy API 地址（默认值，可选）
  codacy-metrics-eslint:latest \
  analyze /app --upload  # --upload 启用数据上报 Codacy

4.3 Docker Compose 配置示例

创建 docker-compose.yml 文件：

version: '3.8'
services:
  eslint-metrics:
    image: codacy-metrics-eslint:latest
    volumes:
      - ./:/app  # 挂载本地项目目录
      - ./.eslintrc.json:/app/.eslintrc.json  # 自定义 ESLint 配置
      - ./.eslintignore:/app/.eslintignore  # 忽略文件配置
    environment:
      - CODACY_PROJECT_TOKEN=your-project-token  # 可选，用于 Codacy 上报
      - LOG_LEVEL=info  # 日志级别（debug/info/warn/error，默认 info）
    command: analyze /app  # 执行分析命令

启动容器：

docker-compose up

4.4 配置参数说明

环境变量（Environment Variables）

挂载卷（Volumes）

5. 注意事项

• 权限问题：挂载本地目录时，容器内用户（默认 nobody）需有读取代码文件的权限，建议通过 chmod 调整本地文件权限或在命令中添加 --user $(id -u):$(id -g) 指定用户。
• 配置优先级：容器内挂载的自定义 ESLint 配置文件优先级高于镜像内置配置，需确保配置文件格式正确（可通过 eslint --print-config 验证）。
• 网络要求：如启用 Codacy 上报（--upload），容器需能访问 Codacy API 地址（默认 [***]），企业版需配置内网地址及端口。