Codacy Analysis CLI Docker镜像文档

一、镜像概述和主要用途

Codacy Analysis CLI Docker镜像是一个轻量级命令行工具镜像，用于在本地环境执行Codacy代码分析。该工具旨在帮助开发者在提交代码前，通过本地运行与Codacy平台一致的代码质量检查，提前发现潜在的代码问题（如语法错误、安全漏洞、代码规范违规等），确保代码符合团队或项目的质量标准。镜像封装了Codacy Analysis CLI的核心功能，无需本地安装依赖，直接通过Docker即可快速启动分析流程。

二、核心功能和特性

2.1 核心功能

• 本地代码质量分析：无需依赖Codacy平台，直接在本地对代码库执行静态代码分析。
• 多工具集成：支持Codacy平台兼容的多种代码分析工具（如ESLint、PMD、Checkstyle、SonarQube等），覆盖多种编程语言。
• 与Codacy配置兼容：支持读取项目根目录下的codacy.yml配置文件，确保本地分析规则与Codacy平台保持一致。
• 多格式报告输出：可生成JSON、HTML、控制台文本等多种格式的分析报告，便于查看和集成。

2.2 特性

• 轻量级：镜像体积小，启动速度快，适合本地开发环境和CI/CD流水线集成。
• 零依赖安装：通过Docker容器化运行，无需在主机配置复杂的分析工具链。
• 灵活配置：支持通过命令行参数或配置文件自定义分析范围、工具和规则。
• 详细日志：提供 verbose 模式，便于调试分析过程中的问题。

三、使用场景和适用范围

3.1 适用场景

• 开发者本地自检：开发过程中实时检查代码质量，减少提交后Codacy平台反馈的问题。
• CI/CD 预检查：在CI/CD流水线中，作为代码提交前的前置检查步骤，提前拦截不合格代码。
• 开源项目贡献：贡献者在提交PR前，通过本地分析确保代码符合项目的质量规范。
• 团队代码审查辅助：代码审查前自动执行分析，减少人工审查的重复工作。

3.2 支持范围

• 编程语言：Java、Python、JavaScript、TypeScript、Go、Ruby、PHP等主流语言（具体取决于集成的分析工具）。
• 分析工具：支持Codacy官方集成的60+种代码质量工具（如ESLint、Pylint、Checkstyle、PMD、Bandit等）。

四、使用方法和配置说明

4.1 基本使用（Docker Run）

4.1.1 简单分析本地项目

将本地代码目录挂载到容器中，执行基础分析：

docker run --rm -v $(pwd):/project codacy/analysis-cli analyze --project-dir /project

• --rm：分析完成后自动删除容器。
• -v $(pwd):/project：将当前目录（项目根目录）挂载到容器内的/project路径。
• analyze：CLI的核心命令，触发代码分析。
• --project-dir /project：指定容器内的项目目录（需与挂载路径一致）。

4.1.2 生成JSON格式报告

指定报告输出路径和格式：

docker run --rm -v $(pwd):/project codacy/analysis-cli analyze \
  --project-dir /project \
  --output /project/codacy-report.json \
  --format json

• --output /project/codacy-report.json：将报告输出到挂载目录下的codacy-report.json文件。
• --format json：指定报告格式为JSON（支持json、html、console，默认console）。

4.1.3 指定分析工具

通过--tools参数自定义分析工具（需工具支持对应语言）：

docker run --rm -v $(pwd):/project codacy/analysis-cli analyze \
  --project-dir /project \
  --tools eslint,pylint \
  --verbose

• --tools eslint,pylint：仅使用ESLint（JavaScript/TypeScript）和Pylint（Python）进行分析。
• --verbose：输出详细分析日志，便于调试。

4.2 Docker Compose 配置示例

创建docker-compose.yml，定义固定的分析配置：

version: '3'
services:
  codacy-analysis:
    image: codacy/analysis-cli
    volumes:
      - ./:/project  # 挂载本地项目目录
    command: >
      analyze
      --project-dir /project
      --output /project/codacy-report.html
      --format html
      --tools eslint,pmd
      --verbose

启动分析：

docker-compose run codacy-analysis

4.3 配置参数说明

4.3.1 常用命令行参数

4.3.2 codacy.yml 配置文件

项目根目录下的codacy.yml文件用于定义分析规则（与Codacy平台配置一致），示例：

exclude_paths:
  - "**/node_modules/**"
  - "**/test/**"
tools:
  eslint:
    enabled: true
    config:
      plugins: ["react"]
      rules:
        react/prop-types: error
  pylint:
    enabled: true
    exclude_paths:
      - "**/migrations/**"

• exclude_paths：排除无需分析的目录/文件。
• tools：配置各工具的启用状态和自定义规则。

五、注意事项

1. 挂载目录权限：确保本地项目目录对容器有读权限（Linux/macOS 可通过chmod调整，Windows 通常无需额外配置）。
2. 工具支持：指定--tools时，需确保工具支持项目使用的编程语言（可参考 Codacy工具列表）。
3. 配置文件：若无codacy.yml，CLI将使用默认规则集，建议从Codacy平台导出项目配置文件以保持一致性。
4. 网络需求：本地分析无需联网，但若需与Codacy平台同步结果（如使用--upload参数），需配置CODACY_API_TOKEN环境变量并确保网络通畅。