📦 Checkly Cli Skills — 监控即代码

技能文档

快速开始

# 创建新的 Checkly 项目
npm create checkly@latest
# 本地测试 checks
npx checkly test
# 部署到 Checkly 云端
npx checkly deploy

什么是 Monitoring as Code？

Checkly CLI 提供了一套原生 TypeScript/JavaScript 工作流，用于大规模地编码、测试并部署 synthetic monitoring。将监控检查定义为代码，本地测试，使用 Git 做版本控制，并通过 CI/CD 管道部署。

核心优势：

• 可编码 – 用 TypeScript/JavaScript 定义检查
• 可测试 – 部署前本地运行检查
• 可评审 – 在 PR 中代码评审监控配置
• 原生 Playwright – 使用标准 @playwright/test 规范
• CI/CD 原生 – 集成到部署管道

技能组织

本技能按 Checkly 领域路由至专门子技能：

入门：

• checkly-auth – 认证设置与登录
• checkly-config – 配置文件（checkly.config.ts）与项目结构

核心工作流：

• checkly-test – 本地测试工作流（npx checkly test）
• checkly-deploy – 部署到 Checkly 云端
• checkly-import – 将现有检查从 Checkly 导入为代码

检查类型：

• checkly-checks – API 检查、浏览器检查、多步检查
• checkly-monitors – 心跳、TCP、DNS、URL 监控
• checkly-groups – 检查分组，便于组织与共享配置

高级：

• checkly-constructs – Constructs 系统与资源管理
• checkly-playwright – Playwright 测试套件与配置
• checkly-advanced – 重试策略、报告器、环境变量、打包

何时用 Checkly CLI，何时用 Web UI

使用 Checkly CLI 的场景：

• 将监控作为代码库的一部分定义
• 在 CI/CD 中自动创建/更新检查
• 开发期间本地测试检查
• 对监控配置做版本控制
• 高效管理大量检查
• 将监控与应用部署集成

使用 Web UI 的场景：

• 首次探索 Checkly
• 查看仪表板与历史结果
• 分析检查失败与事件
• 管理账户级设置
• 配置告警通道（邮件、Slack、PagerDuty）
• 设置私有位置

常见工作流

新项目搭建

# 初始化项目
npm create checkly@latest
cd my-checkly-project
# 认证
npx checkly login
# 本地测试
npx checkly test
# 部署到云端
npx checkly deploy

日常开发

# 创建新的 API 检查
cat > __checks__/api-status.check.ts <<'EOF'
import { ApiCheck, AssertionBuilder } from 'checkly/constructs'
new ApiCheck('api-status-check', {
  name: 'API Status Check',
  request: {
    url: 'https://api.example.com/status',
    method: 'GET',
    assertions: [
      AssertionBuilder.statusCode().equals(200),
      AssertionBuilder.responseTime().lessThan(500),
    ],
  },
})
EOF
# 本地测试
npx checkly test
# 准备好后部署
npx checkly deploy

使用 Playwright 的浏览器检查

# 创建浏览器检查
cat > __checks__/homepage.spec.ts <<'EOF'
import { test, expect } from '@playwright/test'
test('homepage loads', async ({ page }) => {
  const response = await page.goto('https://example.com')
  expect(response?.status()).toBeLessThan(400)
  await expect(page).toHaveTitle(/Example/)
  await page.screenshot({ path: 'homepage.jpg' })
})
EOF
# 本地用 Playwright 测试（更快）
npx playwright test __checks__/homepage.spec.ts
# 通过 Checkly 运行时测试
npx checkly test __checks__/homepage.spec.ts
# 部署
npx checkly deploy

导入现有检查

# 从 Checkly 账户导入所有检查
npx checkly import plan
# 审查生成的代码
git diff
# 提交导入的检查
git add .
git commit -m "Import existing monitoring checks"

决策树

“我应该创建哪种类型的检查？”

`` 你在监控什么？ ├─ REST API / HTTP 端点 │ ├─ 简单可用性 → API Check（请求 + 状态断言） │ ├─ 复杂校验 → API Check（请求 + 多重断言 + 脚本） │ └─ 仅存活/ping → URL Monitor（更简单、更快） │ ├─ Web 应用 / 用户流程 │ ├─ 单页面 → Browser Check（一个 .spec.ts 文件） │ ├─ 多步骤 → Browser Check 或 Multi-Step Check │ └─ 完整测试套件 → Playwright Check Suite（playwright.config.ts） │ └─ 服务健康 / 基础设施 ├─ 定期心跳 → Heartbeat Monitor ├─ TCP 端口 → TCP Monitor ├─ DNS 记录 → DNS Monitor └─ 简单 HTTP → URL Monitor

速查：  
API Check：带断言的 HTTP 请求（状态、头、体、响应时间）  
Browser Check：用于 Web 测试的单个 Playwright 规范文件  
Multi-Step Check：复杂浏览器工作流（已弃用，改用 Browser Check）  
Playwright Check Suite：多测试并行/项目的 Playwright 测试  
Monitors：无需代码执行的简单健康检查  
“本地测试还是直接部署？”

测试层级：  
npx playwright test – 最快，本地 Playwright 执行（仅浏览器检查）  

npx checkly test – 在 Checkly 运行时验证，捕捉兼容性错误  

npx checkly deploy – 部署为持续计划监控  
“基于文件还是基于 construct 的检查？”

模式：  
自动发现：在 checkly.config.ts 中配置 checks.browserChecks.testMatch  

显式构造：从 checkly/constructs 导入并实例化  

Playwright 项目：用不同配置定义多个测试套件  
“配置应该放哪？”

配置优先级（具体覆盖一般）：  
检查级属性（最高优先级）  
CheckGroup 属性  
checkly.config.ts 默认值  
Checkly 账户默认值（最低优先级）  
项目结构
典型的 Checkly CLI 项目：

安装方式
新项目（推荐）

生成脚手架项目，包含：  
带合理默认值的 checkly.config.ts  

__checks__/ 目录中的示例检查  

含 checkly 依赖的 package.json  

已配置的 .gitignore  
现有项目

全局安装（不推荐）

注意：建议使用 npx checkly 以使用项目特定的 CLI 版本。

相关技能

入门：

• 认证设置参见 checkly-auth
• 项目配置参见 checkly-config
• 本地测试工作流参见 checkly-test

创建检查：

• API 与浏览器检查参见 checkly-checks
• 简单健康检查参见 checkly-monitors
• 完整测试套件设置参见 checkly-playwright

高级工作流：

• 部署策略参见 checkly-deploy
• 理解对象模型参见 checkly-constructs
• 重试策略与报告器参见 checkly-advanced

导入现有：

• 从 Web UI 迁移到代码参见 checkly-import`