github/super-linter

GitHub Super-Linter 镜像文档

1. 镜像概述和主要用途

GitHub Super-Linter 是一个基于 Docker 的多语言代码检查工具，集成了超过 20 种主流代码检查器（linter）和格式化工具。其核心用途是通过统一的接口对多语言项目进行自动化代码质量检查，确保代码符合团队或项目的编码规范，减少语法错误、风格不一致等问题。

2. 核心功能和特性

2.1 多语言支持

• 覆盖 20+ 编程语言和文件格式，包括 JavaScript、Python、Java、Go、Ruby、PHP、HTML、CSS、Dockerfile、Markdown、YAML、JSON 等。
• 支持主流 linter，如 ESLint（JavaScript）、Pylint（Python）、Checkstyle（Java）、golint（Go）、RuboCop（Ruby）等。

2.2 灵活配置

• 支持自定义 linter 规则（通过挂载项目本地配置文件，如 .eslintrc、.pylintrc）。
• 可通过环境变量精确控制启用/禁用特定语言检查。
• 支持忽略指定文件或目录（兼容 .gitignore 及 linter 原生忽略机制）。

2.3 集成能力

• 原生支持 GitHub Actions 工作流，可直接集成到 CI/CD 流程。
• 支持本地 Docker 运行，适配开发环境快速验证。
• 生成详细检查报告，支持输出到文件或控制台。

2.4 高效检查

• 支持增量检查（仅检查变更文件）或全量检查（整个代码库）。
• 并行执行多语言检查，提升大型项目检查效率。

3. 使用场景和适用范围

3.1 适用场景

• CI/CD 流程集成：在代码提交、PR 或合并前自动触发检查，阻止不合规代码入库（如 GitHub Actions、GitLab CI 等）。
• 本地开发验证：开发人员在提交代码前本地运行，提前发现问题。
• 多语言项目统一检查：为包含多种语言的项目（如前后端混合项目）提供单一检查入口。
• 代码规范治理：新团队或项目快速落地编码规范，减少人工 code review 成本。

3.2 适用范围

• 开发团队（中小型到大型）、开源项目、企业内部项目。
• 多语言技术栈项目（如微服务、全栈应用）。
• 需要严格控制代码质量和风格一致性的场景。

4. 使用方法和配置说明

4.1 前置条件

• 安装 Docker（20.10+ 版本推荐）。
• 待检查的代码目录（本地路径）。

4.2 Docker 本地运行

4.2.1 基础 Docker Run 命令

bash
docker run --rm \
  -v /path/to/local/code:/app \  # 挂载本地代码目录到容器内 /app
  -e VALIDATE_ALL_CODEBASE=true \  # 检查整个代码库（默认仅检查变更文件）
  -e DEFAULT_BRANCH=main \  # 基准分支（用于增量检查）
  -e LOG_LEVEL=info \  # 日志级别（debug/info/warn/error）
  -e VALIDATE_JAVASCRIPT=true \  # 启用 JavaScript 检查
  -e VALIDATE_PYTHON=true \  # 启用 Python 检查
  ghcr.io/github/super-linter:latest

4.2.2 挂载自定义配置文件

若项目使用本地 linter 配置文件（如 .eslintrc.js），需确保配置文件挂载到容器内代码目录：

bash
docker run --rm \
  -v /path/to/local/code:/app \  # 代码目录（含配置文件）
  -e VALIDATE_JAVASCRIPT=true \
  -e LINTER_RULES_PATH=/app/.github/linters \  # 自定义规则文件路径（可选）
  ghcr.io/github/super-linter:latest

4.3 Docker Compose 配置

创建 docker-compose.yml 文件，定义服务及配置：

yaml
version: '3'
services:
  super-linter:
    image: ***-ghcr.xuanyuan.run/github/super-linter:latest
    volumes:
      - /path/to/local/code:/app  # 挂载本地代码目录
      - /path/to/custom-rules:/app/.github/linters  # （可选）挂载自定义规则目录
    environment:
      - VALIDATE_ALL_CODEBASE=true  # 检查整个代码库
      - DEFAULT_BRANCH=main  # 基准分支
      - LOG_LEVEL=info  # 日志级别
      # 启用特定语言检查
      - VALIDATE_JAVASCRIPT=true
      - VALIDATE_PYTHON=true
      - VALIDATE_YAML=true
      # 忽略文件（可选，格式为逗号分隔的路径）
      - IGNORE_FILES=.github/**/*.md,docs/**/*.md

启动服务：

bash
docker-compose run super-linter

4.4 GitHub Actions 集成

在项目 .github/workflows/ 目录下创建 super-linter.yml 工作流文件：

yaml
name: Code Quality Check
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  super-linter:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 需获取完整历史以支持增量检查

      - name: Run Super-Linter
        uses: github/super-linter@v5  # 使用官方 GitHub Action（基于 Docker 镜像）
        env:
          VALIDATE_ALL_CODEBASE: ${{ github.event_name == 'push' }}  # push 时全量检查，PR 时增量检查
          DEFAULT_BRANCH: main
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # 用于获取 PR 变更信息
          # 启用语言检查
          VALIDATE_JAVASCRIPT: true
          VALIDATE_PYTHON: true
          VALIDATE_YAML: true
          # 日志级别
          LOG_LEVEL: info

5. 配置参数和环境变量

5.1 核心环境变量

5.2 语言检查开关

通过 VALIDATE_<LANGUAGE> 环境变量启用特定语言检查，常用选项：

示例：启用 JavaScript 和 Python 检查：

bash
-e VALIDATE_JAVASCRIPT=true -e VALIDATE_PYTHON=true

6. 常见问题

6.1 如何覆盖默认 linter 规则？

挂载项目本地 linter 配置文件（如 .eslintrc.js、.pylintrc）到代码目录（/app），Super-Linter 会优先使用本地配置。

6.2 检查速度慢如何优化？

• 禁用不需要的语言检查（仅保留项目使用的语言）。
• 使用增量检查（VALIDATE_ALL_CODEBASE=false，默认），仅检查变更文件。
• 确保 Docker 资源充足（如分配足够 CPU/内存）。

6.3 如何忽略特定文件？

• 通过 IGNORE_FILES 环境变量指定（如 IGNORE_FILES=vendor/**/*）。
• 使用 linter 原生忽略机制（如 .eslintignore、.pylintignore）。

7. 参考链接

• 官方仓库：https://github.com/github/super-linter
• 支持的 linter 列表：https://github.com/github/super-linter#supported-linters
• GitHub Actions 文档：https://github.com/marketplace/actions/super-linter