调试

Finch 内置调试器，在开发环境中显示详细的错误页面。

启用调试器

需要两个设置：

// 在 lib/app.dart 中
FinchConfigs(
  enableLocalDebugger: true,   // 设置 1：启用调试器
)

// 在 bin/finch.dart 中
FinchApp.run(
  app: App(),
  isLocalDebug: true,          // 设置 2：以本地调试模式运行
)

两个设置都必须为 true 才能显示调试错误页面。

`isLocalDebug` 的计算方式

通常从环境变量读取 isLocalDebug：

FinchApp.run(
  app: App(),
  isLocalDebug: env.get('APP_ENV') == 'local',
)

这样，通过在部署时设置 APP_ENV=production 即可禁用调试器。

模板变量

在 Jinja 模板中，isLocalDebug 可用：

{% if isLocalDebug %}
  <div class="debug-bar">
    环境：开发 | 版本：{{ appVersion }}
  </div>
{% endif %}

Terminal 面板

当应用以 finch serve（而不是普通的 dart run）启动时，CLI 会在 --terminalPort（默认 8282）上开启一个 WebSocket 服务器，用于流式传输正在运行进程的 stdout/stderr。调试栏的 Terminal 标签会自动连接到这个端口，因此你无需切换到终端窗口即可查看服务器日志和控制台输出，还可以从浏览器向正在运行的进程发送命令。

# 使用自定义的终端端口
finch serve --terminalPort 9000

这项功能只能通过 finch serve 使用，因为正是这个进程负责启动应用并将 FINCH_TERMINAL_PORT 注入其环境变量中。直接使用 dart run 运行应用会导致 Terminal 标签处于未连接状态。

DartDevTools 面板

finch serve 还会以 --enable-vm-service=8181/0.0.0.0 --disable-service-auth-codes 参数启动应用，将 Dart VM service 绑定到所有网络接口（而不仅仅是 localhost），使其在 Docker 容器内部也能够被访问。调试栏内嵌了一个 DevTools 标签，它会连接到端口 8181 上的 VM service，让你可以直接在浏览器中查看正在运行应用的内存、性能和日志视图。

如果你在 Docker 中运行 Finch，请确保在应用端口之外也发布了 8181 和 8282 端口——参见 Docker 部署 Finch。

错误页面

启用调试器时：

未处理的错误在浏览器中显示完整的堆栈跟踪
404 和 500 错误显示美观、信息丰富的页面
请求信息（headers、params、body）可见

生产模式（isLocalDebug: false）时：

向用户显示通用错误页面
堆栈跟踪记录到控制台，而不是浏览器

本页内容

调试