CLI 使用文档

使用与网站相同的规则和报告 schema，检查公网 URL、本地 HTML 文件和站点构建目录中的 Open Graph 元数据。

需要 Node.js 20 或更高版本。npx 会下载并运行公开的 @og-kit/cli 包；安装后的可执行文件名为 og-kit。

快速开始

无需全局安装。CI 中建议把 @og-kit/cli 固定为 devDependency，再从 package script 运行 og-kit。

npx --yes @og-kit/cli check https://example.com
npx --yes @og-kit/cli check ./index.html --base-url https://example.com
npx --yes @og-kit/cli check ./dist --base-url https://example.com

输入方式

`公网 URL`	`https://example.com`	抓取并检查一个公开页面。
`HTML 文件`	`./index.html`	检查单个本地文件；标签含相对 URL 时请加 --base-url。
`目录`	`./dist`	递归检查 HTML 构建产物并输出站点级汇总。
`多个目标`	`./a.html ./b.html`	以受控并发一次检查多个目标。

目录默认包含 **/*.html，并忽略常见的依赖、版本控制和缓存目录。未提供 --base-url 时，需要公网页面身份的规则会明确列为“已跳过”，不会误报为通过。

输出格式

`human（默认）`	供人阅读的问题、跳过项、得分与目录汇总；文案和布局不是机器接口。
`--json`	稳定的 core OgReport JSON schema。
`--sarif`	用于 GitHub Code Scanning 等工具的 SARIF 2.1.0。
`--junit`	用于 CI 测试结果面板的 JUnit XML。
`--quiet / -q`	只显示人类可读的问题，不显示标题和汇总。
`--summary`	只显示人类可读的汇总统计。

全部选项

`--fail-on <error\|warn\|info>`	使门禁失败的最低级别；默认 error，或读取配置的 failOn。
`--concurrency <n>`	最大并行目标数，默认 6。
`--config <path>`	加载指定的 ogkit.config.json/js/mjs/cjs/ts。
`--no-config`	关闭向上查找配置文件。
`--disable <id>`	禁用规则；可重复传入或使用逗号分隔。
`--only <id>`	仅运行指定规则；可重复传入或使用逗号分隔。
`--base-url <url>`	用于解析页面和资源 URL 的公网 HTTP(S) 基础地址。
`--include <glob>`	目录包含 glob，可重复；默认 */.html。
`--ignore <glob>`	额外的目录忽略 glob，可重复。
`--baseline <path>`	读取基线；匹配的问题不会使 CI 失败。
`--update-baseline`	用本次运行写入或刷新所选基线。
`--no-color`	关闭 human 输出中的 ANSI 颜色。
`--lang <en\|zh>`	设置 CLI 语言；依次回退到 OGKIT_LANG 和 POSIX locale。

配置文件

OGKit 从当前目录向文件系统根目录查找配置。未知字段和非法值会直接报错；配置内的路径相对于配置文件解析。

// ogkit.config.mjs
export default {
  baseUrl: "https://example.com",
  include: ["**/*.html"],
  ignore: ["archive/**"],
  failOn: "warn",
  baseline: ".ogkit-baseline.json",
  rules: {
    "og-description-missing": "error",
    "description-too-short": "off"
  }
};

使用基线渐进接入

基线让已有项目在不隐藏当前问题的前提下执行“不得新增回归”。首次生成并提交 JSON 文件，之后在门禁中持续使用。

og-kit check ./dist --base-url https://example.com \
  --baseline .ogkit-baseline.json --update-baseline

og-kit check ./dist --baseline .ogkit-baseline.json

基线匹配只影响 CI 门禁，--json 中仍保留完整问题。仅在团队明确接受的存量问题变化时主动运行 --update-baseline。

CI 示例

用机器格式保存产物，用退出码执行门禁。以下示例假设 CLI 已作为固定版本的 devDependency 安装。

npm install --save-dev @og-kit/cli

{
  "scripts": {
    "check:og": "og-kit check ./dist --base-url https://example.com --fail-on warn",
    "check:og:sarif": "og-kit check ./dist --base-url https://example.com --sarif > ogkit.sarif"
  }
}

# GitHub Actions steps
- run: npm ci
- run: npm run check:og

HTML 内联例外

本地 HTML 可以声明经过评审的例外，-- 后的原因必填。由于并非所有问题都有行号，两种写法目前都作用于整份文档。

<!-- ogkit-disable og-description-missing -- landing page intentionally uses the title only -->
<!-- ogkit-disable-next-line description-too-short -- approved campaign copy -->

退出码

`0`	应用基线后，没有达到 --fail-on 级别的问题。
`1`	至少一个问题达到门禁级别。
`2`	参数或配置无效、输入或 I/O 失败，或工具意外失败。

帮助与版本

已安装 CLI 的帮助是对应版本的权威参考。--version 会分行输出 CLI、引擎、规则集与报告 schema 版本。

npx --yes @og-kit/cli check --help
npx --yes @og-kit/cli --version