跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

本地资源浏览器

最后更新 查看 MarkdownAgent 设置

本地资源浏览器是一个基于浏览器的界面,用于在开发期间查看和编辑本地绑定中的数据,并调试 Worker 调用。它可在本地开发服务器的 /cdn-cgi/local/explorer 路径访问。

无需运行 CLI 命令或编写临时代码来检查本地状态,您可以在浏览器中打开本地资源浏览器以操作数据、查看跟踪并搜索日志。这在需要填充测试数据、验证 Worker 写入的内容、调试失败请求,或对本地 D1 数据库运行 SQL 查询时很有用。

Local Explorer 可搭配 Cloudflare CLI(cf dev)、Wrangler和 Cloudflare Vite 插件使用。cf dev 会启动由框架或已安装的 Cloudflare 构建工具提供的开发服务器。

前提条件

请使用 Wrangler 4.118.0 或更高版本,或 Cloudflare Vite 插件 1.50.0 或更高版本。对于 cf dev,这些要求适用于它启动的开发服务器。详情请参阅 How cf runs your project。

打开 Local Explorer

  1. 启动本地开发会话:

    对于已通过 cloudflare.config.ts配置的项目,请运行:

    cf dev
    npx wrangler dev
    npx vite
  2. 将开发服务器显示的 URL 追加 /cdn-cgi/local/explorer,然后在浏览器中打开该地址。例如,Vite 默认端口对应 http://localhost:5173/cdn-cgi/local/explorer,Wrangler 默认端口对应 http://localhost:8787/cdn-cgi/local/explorer。

Local Explorer 默认可用,并会自动检测 cloudflare.config.ts或 Wrangler 配置中定义的绑定。

支持的绑定

本地资源浏览器支持以下绑定类型:

绑定 查看 编辑
KV 浏览键、查看值和元数据 创建、更新和删除键值对
R2 列出对象、查看元数据 上传和删除对象
D1 浏览表和行、运行 SQL 查询 通过 SQL 插入、更新和删除行
Durable Objects(SQLite 存储) 浏览 SQLite 表和行、运行 SQL 查询 通过 SQL 插入、更新和删除行
Workflows 列出实例、查看状态和步骤历史 触发新运行、重试失败的实例
发送电子邮件(send_email) 列出已发送邮件、查看内容和标头 仅查看
Flagship 列出功能标志、测试标志评估 创建、更新和删除标志,编辑定向规则和 rollout

本地资源浏览器还支持以下 Worker 触发器:

触发器 查看 测试
Email Routing 列出收到的邮件、查看内容、标头和处理结果 发送测试邮件,重新发送或编辑后重新发送捕获的邮件
Cron Triggers 查看配置的 cron 计划和调用结果 使用已配置或临时 cron 表达式以及选定的计划时间调用 scheduled() 处理程序

D1 与 Durable Objects SQL Studio

对于 D1 数据库和使用 SQLite storage API 的 Durable Objects,本地资源浏览器包含 SQL Studio。这与 Cloudflare 仪表板中为已部署 D1 数据库提供的体验相同。它提供可视化表浏览器(支持内联编辑)和 SQL 查询编辑器,可运行任意查询。

测试 Cron Triggers

Local Explorer 可以向 Worker 的 scheduled() 处理程序发送一次性调用。它支持已配置的 Cron Triggers 和临时表达式。

测试 Cron Trigger 需要 Wrangler 4.139.0 或更高版本,或 Cloudflare Vite 插件 1.60.0 或更高版本。这些要求也适用于 cf dev 启动的开发服务器。

Worker 必须导出 scheduled() 处理程序。如需测试已配置的表达式,请为当前环境至少定义一个 Cron Trigger。临时表达式无需配置。

  1. 在 Local Explorer 中,选择要测试的 Worker,然后选择 Cron Triggers > Configured Crons。
  2. 在 Scheduled time 下选择 Now。如需测试其他时间,请选择 Add preset,然后输入 UTC 日期和时间或纪元毫秒数。
  3. 选择已配置 Cron 表达式旁边的 Trigger。
  4. 检查执行结果、noRetry() 状态、已派发的表达式和计划时间。
  5. (可选)如需测试其他表达式,请选择 Cron Triggers > Ad-Hoc Triggers。选择 Add trigger,输入或构建表达式,然后选择 Trigger。

完整调用日志可在拥有该 Worker 的开发会话中查看。该会话必须已开启 Observability。

构建临时表达式

在 Ad-Hoc Triggers 下,选择 Expression 以输入准确表达式。选择 Build expression 可创建常见的五字段 UTC 表达式。系统始终会派发该行中显示的准确表达式。

构建器支持分钟、小时、月中日期和月份间隔,也支持每日、指定星期和每月计划。若要创建更具体的计划,请使用以下类 Quartz 选项:

选项 行为
L 选择最后一天或最后一个指定星期几
W 选择最近的工作日
LW 选择当月最后一个工作日
# 选择指定星期几的某次出现

步长值从字段最小值开始,并在字段边界处重置。日期步长从第 1 天开始,月份步长从 January 开始。29 到 31 这些日期在缺少相应日期的月份不会运行。

切换到 Build expression 不会替换当前表达式。更改有效的构建器字段后,会重新生成表达式。如需使用构建器不支持的语法,请选择 Expression 并直接输入。

临时触发器和计划时间预设会存储在浏览器中。Local Explorer 会将其限定在本地项目和 Worker 范围内。它们不会更改 cloudflare.config.ts、Wrangler 配置或已部署的 Cron Triggers。

每次调用都是一次性本地测试。本地开发不会自动运行 Cron Triggers。

可观测性

在本地开发期间,Local Explorer 会自动捕获每次 Worker 调用的跟踪和日志,无需修改代码。此功能适用于 cf dev、wrangler dev 和 Cloudflare Vite 插件。你可以直接在开发浏览器中查看与生产环境相同的监测信息,包括调用日志、绑定操作、计时和控制台输出,详见 Workers Logs和跟踪。

日志

Logs 视图捕获 Worker 的所有 console.* 输出。按级别(error、warn、info、log、debug)过滤或按文本搜索以查找特定消息。

跟踪

每次 Worker 调用都显示为一条跟踪。选择任意跟踪即可查看每个绑定操作及其计时、状态和错误详情。

跟踪还会捕获通过远程绑定进行的操作,因此你可以检查从本地运行的 Worker 到已部署资源的调用。

例如,如果请求进行两次 D1 调用且第二次失败,跟踪会准确显示哪次调用成功、哪次出错,而无需添加 console.log() 或 try/catch 块。

POST /api/todos 的跟踪视图,显示两个 D1 数据库 span:第一次 INSERT 成功,第二次因错误 "no such table: audit_log" 失败

API

本地资源浏览器在 /cdn-cgi/local/explorer/api 暴露 API,以编程方式提供与浏览器界面相同的操作。该 API 提供 OpenAPI 规范 ↗,描述所有可用端点、参数和响应格式。

以下示例使用端口 8787。请将其替换为你的开发服务器端口,例如 Vite 使用的 5173。

获取 OpenAPI 规范:

curl http://localhost:8787/cdn-cgi/local/explorer/api

该 API 提供 POST /cdn-cgi/local/explorer/api/local/scheduled?worker=<WORKER_NAME>,用于发起定时调用。请求会指定一个确切的 Worker,并接受必需的 Cron 表达式和可选的计划时间。请求示例请参阅在本地测试 Cron Triggers。

与 AI 代理配合使用

检测到 AI Agent 时,开发服务器会输出提示,其中包含 Local Explorer API 端点。使用 cf dev 启动服务器时也适用。Agent 可以从该端点获取 OpenAPI 规范 ↗以发现所有可用操作,然后调用 API 读取或修改本地数据、查询跟踪和日志,并调试 Worker。

提示包含 API URL 和相关端点:

This dev session is running in an AI agent.

The Local Explorer API is available at
http://localhost:8787/cdn-cgi/local/explorer/api

...

Debug with traces:
POST /cdn-cgi/local/explorer/api/local/observability/query -- query traces and logs with SQL

当您希望代理执行以下操作时,这可以作为 CLI 的替代方案:

  • 在本地 KV 命名空间或 D1 数据库中填充测试数据
  • 在调试期间检查 Durable Object 的状态
  • 使用不同输入数据触发或重试 Workflow 运行
  • 使用指定的 Cron 表达式和时间调用 scheduled() 处理程序
  • 将测试文件上传到本地 R2 存储桶
  • 查找最近出错的请求并深入失败的 span

这篇文档对您有帮助吗?