文档

blight 是一个 PHP CLI 工具，用于检测本地机器与 CI/CD 环境之间的版本和环境漂移。运行一条命令即可确切了解为何本地构建通过而 CI 失败。

简介

由环境不匹配引起的大多数 CI 失败在到达构建服务器之前是不可见的。blight 实时将您的本地环境与 GitHub Actions 日志进行比较——在推送之前发现 PHP 版本不匹配、缺少 Node.js 和 ENV 变量漂移。

• 解析 GitHub Actions 日志文件中的错误、警告和失败步骤
• 将本地 PHP、Node.js 和 ENV 状态与 CI 使用的进行比较
• 将差异分类为 严重、警告 或 信息
• 以交互式终端表格或机器可读 JSON 输出

安装

克隆并在本地运行

git clone https://github.com/blight-dev/blight.git
cd blight
composer install
php bin/blight --version

Composer 全局安装 （发布到 Packagist 后可用）

composer global require blight/blight
blight --version

要求：PHP 8.2+、Composer 2.x、ext-json

快速入门

捕获 CI 不匹配的最快方式：

php bin/blight info

php bin/blight parse --log /path/to/github-actions.log

php bin/blight compare --log /path/to/github-actions.log

php bin/blight report

blight info

$ php bin/blight info
blight.dev – Local Environment Inspector
=========================================
PHP Version   8.2.0
Node Version  20.11.0
OS            Linux x86_64
Branch        main / abc1234
DATABASE_URL  [REDACTED]

blight parse

$ php bin/blight parse --log examples/ci-major-mismatch.log
Steps: Set up PHP ✓, Set up Node.js ✓, Run tests ✗
Errors (2): PHP Fatal error in Util.php:42, exit code 255
Summary: 3 steps, 1 failed, 2 errors

blight compare

┌──────────┬─────────────────┬───────────┬────────┬─────────────────────────────────────┐
│ Severity │ Key             │ Local     │ CI     │ Message                             │
├──────────┼─────────────────┼───────────┼────────┼─────────────────────────────────────┤
│ CRITICAL │ PHP Version     │ 8.2.0     │ 7.4.33 │ Major version mismatch — will fail  │
│ WARNING  │ Node.js Version │ not found │ 18.1.0 │ CI uses Node.js, not installed here │
└──────────┴─────────────────┴───────────┴────────┴─────────────────────────────────────┘

blight report

blight history Paid

blight init

$ php bin/blight init
? API key (leave blank for free plan): blight_pro_xxxxxxxxx
? Default repo name: my-app
? Enable Slack alerts? No
✔ Created .blight.json

配置 — .blight.json

blight 在当前目录中查找 .blight.json 文件。使用 blight init 创建或手动创建：

{
  "api_key": "blight_pro_xxxxxxxxxxxxxxxx",
  "repo": "my-app",
  "alerts": {
    "slack_webhook": "https://hooks.slack.com/services/...",
    "discord_webhook": ""
  }
}

输出格式

所有命令都支持 --output json 以获取结构化机器可读输出。适用于脚本编写、CI 集成或仪表板。

{
  "command": "compare",
  "repo": "my-app",
  "timestamp": "2026-04-09T12:00:00Z",
  "mismatches": [
    {
      "severity": "CRITICAL",
      "key": "PHP Version",
      "local": "8.2.0",
      "ci": "7.4.33",
      "message": "Major PHP version mismatch"
    }
  ],
  "summary": { "critical": 1, "warning": 0, "info": 0 }
}

静默模式 (-q)

为任意命令添加 -q 以获取单行摘要。适合 shell 脚本和 CI 流水线。

$ php bin/blight compare --log ci.log -q
CRITICAL: 1, WARNING: 1, Total: 2

$ php bin/blight parse --log ci.log -q
Errors: 2, Warnings: 0, Failed steps: 1

Webhook 通知 Paid

每当 compare 发现差异时，blight 可以发送 Webhook 通知。支持 Slack 和 Discord（任何接受 JSON POST 的服务）。

通过 .blight.json 配置

{
  "api_key": "blight_pro_xxxxxxxxxxxxxxxx",
  "repo": "my-app",
  "alerts": {
    "slack_webhook": "https://hooks.slack.com/services/T.../B.../xxx",
    "discord_webhook": "https://discord.com/api/webhooks/..."
  }
}

或通过 compare 内联传入

php bin/blight compare --log ci.log \
  --alert slack \
  --webhook-url https://hooks.slack.com/services/...

GitHub Actions 集成

blight 附带一个可直接使用的 GitHub Actions 流水线，位于 .github/workflows/ci.yml。它在每次推送和拉取请求时运行，涵盖 lint、静态分析和 blight 自身的 dogfood 步骤。

name: CI

on:
  push:
  pull_request:

jobs:
  build:
    name: PHP ${{ matrix.php-version }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php-version: ["8.2"]

    steps:
      - uses: actions/checkout@v4

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}

      - name: Validate composer.json
        run: composer validate --strict

      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
          path: vendor
          key: ${{ runner.os }}-composer-${{ hashFiles('composer.lock') }}

      - name: Install dependencies
        run: composer install --no-interaction --prefer-dist

      - name: Lint PHP syntax
        run: find src/ -name "*.php" -print0 | xargs -0 -n1 php -l

      - name: PHPStan static analysis
        run: vendor/bin/phpstan analyse --no-progress --error-format=github

      - name: blight — parse sample log (dogfood)
        continue-on-error: true
        run: php bin/blight parse --log examples/ci-sample.log

      - name: blight — compare local vs CI sample (dogfood)
        continue-on-error: true
        run: php bin/blight compare --log examples/ci-sample.log

在您自己的 CI 中使用 blight

要在任何现有 GitHub Actions 工作流中将 blight 用作漂移检测步骤，请添加一个下载实际 CI 日志并运行 compare 的步骤：

- name: Detect environment drift with blight
  run: |
    php bin/blight compare --log "${{ runner.temp }}/ci-run.log" -q
  continue-on-error: true

示例日志格式

blight 解析从仓库 Actions 选项卡下载的 GitHub Actions 日志文件。解析器查找特定模式：

examples/ 目录包含两个可用于测试的参考日志：

• examples/ci-sample.log — 包含失败测试步骤和错误行的真实 7 步日志
• examples/ci-major-mismatch.log — 显示 PHP 7.4 与 8.x 主版本不匹配的日志

php bin/blight parse --log examples/ci-sample.log
php bin/blight compare --log examples/ci-major-mismatch.log

Pre-push Git 钩子

通过将 blight 接入 Git pre-push 钩子，在推送前捕获 CI 漂移。保存最新的 CI 日志，并在每次推送时自动进行比较：

#!/bin/sh
# blight pre-push hook — abort if CRITICAL drift is found
LOG="$HOME/.blight/last-ci.log"
if [ -f "$LOG" ]; then
  RESULT=$(php bin/blight compare --log "$LOG" -q 2>&1)
  echo "$RESULT"
  if echo "$RESULT" | grep -q "CRITICAL: [1-9]"; then
    echo "blight: CRITICAL environment drift detected. Fix before pushing."
    exit 1
  fi
fi
exit 0

chmod +x .git/hooks/pre-push

PHPStan 集成

blight 使用 PHPStan 在第 5 级进行静态分析。配置位于项目根目录的 phpstan.neon 中：

includes:
    - phpstan-baseline.neon

parameters:
    level: 5
    paths:
        - src/

phpstan-baseline.neon 文件将代码库中预先存在的错误设为基线，这样只有新代码必须是干净的。修复错误后重新生成基线：

vendor/bin/phpstan analyse --generate-baseline --memory-limit=512M

PHPStan 通过 CI 流水线在每次推送时自动运行，并使用 --error-format=github 直接在 GitHub 拉取请求中输出注释。

多语言支持

blight 支持英语、土耳其语和简体中文输出。通过 CLI 标志、配置文件或环境变量设置首选语言。

用法

php bin/blight info --lang tr
php bin/blight compare --log ci.log --lang zh

{
    "lang": "tr"
}

BLIGHT_LANG=tr php bin/blight info

优先级顺序

1. --lang CLI 标志
2. .blight.json "lang" 字段
3. BLIGHT_LANG 环境变量
4. 默认：en（英语）

支持的语言

免费计划

• 每个仓库 5 次分析
• 1 个仓库
• 所有命令可用
• 历史记录限于最近 5 条
• 无 JSON 历史导出

付费计划

• 无限次分析
• 无限仓库
• 带筛选的完整历史
• JSON 历史导出
• Slack 和 Discord 通知 Webhook
• 优先支持

在 .blight.json 中或通过 blight init 设置 API 密钥以激活付费功能。