Dataform 的 JavaScript 代码在编译阶段执行（生成 SQL），而非运行时，因此 console.log 不会输出到 Cloud Logging；真正的调试需借助编译期日志、dataform.compile() 返回值或预编译检查等替代方案。
dataform 的 javascript 代码在编译阶段执行（生成 sql），而非运行时，因此 `console.log` 不会输出到 cloud logging；真正的调试需借助编译期日志、`dataform.compile()` 返回值或预编译检查等替代方案。
在 Dataform 中，开发者常误以为 JavaScript 逻辑（如 ref(), declare(), 或自定义转换函数）会在工作流执行时运行，从而尝试用 console.log 输出中间状态以辅助调试。但事实是：Dataform 的 JS 代码仅在编译期（compile time）执行——即当你运行 dataform compile 或触发 CI/CD 构建时，JS 被解析、求值，并最终生成可部署的 SQL 语句（如 CREATE TABLE AS SELECT...）。该过程完全脱离 SQL 执行环境，也不连接目标数据仓库，更不会将 console.log 推送至 Google Cloud Logging。
这意味着以下代码不会产生可观测的日志：
// ❌ 无效：编译期 console.log 不会被捕获，且无运行时上下文
ref("source_table");
console.log("Processing GitHub metadata..."); // 此行静默丢弃✅ 正确的调试与可观测性实践包括：
-
利用 dataform.compile() 的返回值进行本地验证
在本地运行 dataform compile --json，将输出结构化 JSON（含所有声明的表、操作、依赖关系），可用于检查生成逻辑是否符合预期：dataform compile --json > compiled.json
然后通过 jq 或脚本解析关键字段，例如验证某张表是否被正确定义：
jq '.tables[] | select(.name == "github_parsed_files")' compiled.json
-
使用 fail() 主动中断编译并提供上下文信息
当需验证配置或数据结构时，可用 fail() 抛出带描述的错误（仅在编译失败时可见，适合 CI 检查）：const githubConfig = dataform.projectConfig.vars?.github; if (!githubConfig) { fail("Missing required project var: github (owner/repo)"); } -
将调试信息注入生成的 SQL 注释中
利用模板字符串将元数据写入 SQL 的 -- 注释，部署后可在数据仓库查询历史或视图 DDL 中查看：const debugInfo = `-- DEBUG: processed ${files.length} YAML files from ${repo}`; publish("github_metadata").query(ctx => `${debugInfo}\nSELECT ...`); 对复杂逻辑做单元式 JS 验证（推荐）
将核心解析逻辑（如 GitHub API 响应解析、YAML 解析器）抽离为独立 .js 工具模块，在 Node.js 环境下编写 Jest 测试，确保逻辑正确后再集成进 Dataform 脚本。
⚠️ 注意事项：
- 不要依赖 console.* 进行运行时观测；它在 Dataform 编译流程中无意义；
- 避免在 JS 逻辑中调用外部 HTTP 请求（如 fetch）——编译期无网络沙箱，且违反不可变性原则；
- 所有动态行为（如读取 GitHub 文件）必须通过 Dataform 内置机制实现（例如配合 dataform.run() 的自定义操作，或预处理为静态 JSON 并作为 vars 注入）。
总结而言，Dataform 的“代码即配置”范式要求开发者转变调试思维：从运行时日志转向编译期验证、结构化输出和防御性声明。掌握 compile --json、fail() 和模块化设计，才能高效构建健壮、可维护的数据工程流水线。
