尧图网页设计 
Dagger TypeScript SDK 详解安装、ESM 配置与 connect 连接模型实战指南【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/daggerDagger 的 TypeScript SDKnpm 包名dagger.io/dagger是你在 Node.js 项目中以 TypeScript/JavaScript 编写并执行 CI/CD 管道的官方客户端。本文基于仓库中 version-0.20 的 TypeScript SDK 参考文档结合 sdk/typescript 目录下的真实源码完整讲解 SDK 的安装方式、type: module与NodeNext等 ESM 强制配置的原因、connect/connection两个入口函数的连接机制与ConnectOpts参数以及 SDK 贡献者所需的npm link本地联调与watch编译流程读完即可在自己的 Node 项目中跑通 Dagger 管道并理解客户端与引擎的交互方式。什么是 Dagger TypeScript SDKDagger 官方文档将 SDK 定位为它包含了用 TypeScript 或 JavaScript 开发 CI/CD 管道所需的一切且这些管道可以运行在任何 OCI 兼容的容器运行时上。从 sdk/typescript/package.json 可以确认 SDK 的关键工程事实包名dagger.io/dagger模块类型type: module即以 ESMECMAScript Modules方式发布这是后文要求宿主项目同样设为 ESM 的根本原因运行环境engines: { node: 20 }即要求 Node 20 及以上版本导出入口exports字段暴露了.映射到./dist/src/index.js即主入口的类型声明位于./dist/src/index.d.ts和./telemetry映射到./dist/src/telemetry/index.js两个子路径遥测模块可以单独按需引入底层通信栈依赖graphql-request执行 GraphQL 查询、graphql/graphql-tag构造查询、grpc/grpc-jsgRPC 通道、node-fetchHTTP以及一组 OpenTelemetry 包opentelemetry/sdk-node、OTLP/Jaeger exporter 等说明客户端通过 GraphQL over 会话通道与 Dagger 引擎交互并内建分布式追踪能力。安装文档给出的标准安装命令是npm install dagger.io/dagger --save-dev安装后你就可以从包中导入connect等符号。从 sdk/typescript/src/index.ts 可以看到主入口的完整导出面export { GraphQLClient } from graphql-request // Telemetry export * from ./telemetry/index.js // Default client bindings export * from ./api/client.gen.js // Common errors export * from ./common/errors/index.js // Connection for library export type { CallbackFct } from ./connect.js export { connect, connection } from ./connect.js export type { ConnectOpts } from ./connectOpts.js // Export dagger connection context export { Context, BaseClient } from ./common/context.js // Module library export * from ./module/decorators.js export { entrypoint } from ./module/entrypoint/entrypoint.js export { getRegisteredClass } from ./module/registry.js由此可知 SDK 对外提供了四类能力connect/connection连接函数与ConnectOpts配置类型自动生成的 API 客户端绑定./api/client.gen.js即 DAGGER 核心 API 的 TypeScript 类型化方法链例如client.host()、client.container().from(...)等结构化错误类型./common/errors/包括DaggerSDKError、GraphQLRequestError、EngineSessionConnectionTimeoutError、NotAwaitedRequestError、ExecError等便于在管道中做细粒度错误处理模块开发支持./module/子系统的装饰器function、module、entrypoint等用于编写自定义 Dagger 模块而非仅调用核心 API。连接引擎connect 与 connectionSDK 与引擎的交互入口在 sdk/typescript/src/connect.ts 中实现提供了两个函数connect回调式 API 客户端export async function connect( cb: CallbackFct, config: ConnectOpts {}, ): Promisevoid其中CallbackFct的签名为(client: Client) Promisevoid。connect的内部流程是通过withGQLClient建立一个连接 Dagger 引擎的 GraphQL 客户端需要时自动拉起引擎会话见下文构造Connection与Context并创建自动生成的Client实例版本兼容性检查调用client.version()若不兼容会打印failed to check version compatibility警告——这解释了为什么 SDK 与 Dagger 引擎版本需要匹配将client交给你的回调函数执行具体管道逻辑。典型用法对应 sdk/typescript/src/connect.ts 的 JSDoc 示例风格import { connect } from dagger.io/dagger await connect(async (client) { const container await client .container() .from(alpine) .withExec([apk, add, curl]) .withExec([curl, https://dagger.io/]) })connection基于全局客户端connection接收一个无参异步函数使用 SDK 内置的全局 Dagger 客户端globalConnection执行并把执行包裹在 OpenTelemetry context 中做追踪传播结束时finally复位全局客户端并关闭遥测await connection(async () { // 使用全局 dag 客户端…… }, { LogOutput: process.stderr })ConnectOpts连接配置项ConnectOpts定义在 sdk/typescript/src/connectOpts.ts共三个可选字段字段类型说明Workdirstring覆盖 Dagger 工作目录默认process.cwd()LoadWorkspaceModulesboolean是否为该连接加载 workspace 模块默认只暴露核心 APILogOutputnode:stream的Writable开启日志输出可指向process.stdout/process.stderr等任意可写流引擎会话的建立与复用sdk/typescript/src/common/graphql/connect.ts 中的withGQLClient揭示了会话建立策略复用已有会话若环境变量DAGGER_SESSION_PORT已设置例如代码运行在dagger call或 dagger 引擎会话内部则必须同时提供DAGGER_SESSION_TOKEN缺失会直接抛错DAGGER_SESSION_TOKEN must be set if DAGGER_SESSION_PORT is set客户端直接以port token连接现有会话不再新起引擎自动供给provisioning否则动态import并调用 sdk/typescript/src/provisioning 的withEngineSession按需下载/启动本地引擎二进制并建立新会话失败时包装为failed to execute function with automatic provisioning错误。这也意味着 SDK 既可独立运行也能作为 Dagger 模块内部逻辑的一部分复用宿主会话避免重复拉起引擎。本地开发在自有 Node 项目中联调 SDK文档的“Local development”一节面向需要修改 SDK 源码、并在本地 Node 项目里直接测试的贡献者。以下四步完整继承原文档并补充仓库源码层面的解释。1. 创建新的 Node 项目已有 Node 项目可跳过此步mkdir my-test-ts-project # Init project (you may use yarn or pnpm) npm init -y # Add typescript npm install typescript ts-node --save-dev # Init typescript project npx tsc --init2. 更新项目配置为 ESM原文档强调Dagger 以type: module发布 SDK因此宿主项目的package.json必须设置相同的模块类型否则在 Node 的 CJS 上下文中会触发 ESM/CJS 导入错误。从项目根目录执行npm pkg set typemodule同时必须将tsconfig.json的module设为NodeNextmodule: NodeNext这个要求与 SDK 自身的编译配置一致sdk/typescript/tsconfig.json 中 SDK 使用module: Node16/moduleResolution: Node16、target: ES2022并开启emitDecoratorMetadata模块装饰器依赖。宿主项目采用NodeNext是与之配套的模块解析策略保证 ESM 导入含./xxx.js后缀写法行为一致。3. 通过 npm link 建立本地符号链接进入仓库中的 SDK 目录创建全局链接cd path/to/dagger/sdk/typescript # go into the package directory npm link # creates global link再回到你的业务项目目录链接安装该包cd path/to/my_app # go into your project directory. npm link dagger.io/dagger # link install the package此后对path/to/dagger/sdk/typescript的改动会实时反映在path/to/my_app/node_modules/dagger.io/dagger中实际指向 SDK 构建产物dist/目录。4. watch 模式编译开始贡献修改 SDK 源码期间应保持 watch 编译cd path/to/dagger/sdk/typescript # go into the package directory yarn watch # Recompile the code when input files are modified对照 sdk/typescript/package.json 的scripts字段可知watch实际执行的是tsc -w增量监听编译build则是普通的tsc测试脚本包括test:nodemocha与test:bunbun run --bun mocha。因此联调流程为一边yarn watch持续产出dist/一边在自己的项目里import { connect } from dagger.io/dagger即可像使用官方发布版一样导入本地 SDKimport { connect } from dagger.io/daggerSDK 的构建、测试与校验脚本速查在深入本地开发前熟悉 sdk/typescript/package.json 中的脚本有助于选择正确的验证手段脚本命令用途buildtsc一次性编译到dist/watchtsc -w监听源码变更并持续重编译test:node/test:bunmocha/bun run --bun mocha在 Node 或 Bun 运行时跑 mocha 测试lint/fmtyarn eslint ...ESLint 检查与自动修复docs:lint/docs:fmt对docs/current_docs下的.ts片段按eslint-docs.config.js校验保证官方文档中 TypeScript 示例与 SDK 真实类型一致值得注意的是docs:lint它用独立的 eslint-docs.config.js 对docs/current_docs中的.ts文档代码片段做类型级校验说明文档示例是被当成真实代码对待的这也是引用 SDK 行为时应优先以源码为准的原因。小结安装npm install dagger.io/dagger --save-dev要求 Node 20包以 ESM 发布type: module。连接connect提供回调式类型化客户端并做引擎版本检查connection使用全局客户端并内置 OTel 传播withGQLClient会优先复用DAGGER_SESSION_PORT/DAGGER_SESSION_TOKEN指定的既有会话否则自动供给新引擎会话。配置ConnectOpts支持Workdir默认process.cwd()、LoadWorkspaceModules、LogOutput三项。本地联调宿主项目必须npm pkg set typemodule且tsconfig.json使用NodeNext再用npm linkyarn watch实现源码级热替换开发。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dagger TypeScript SDK 详解：安装、ESM 配置与 connect 连接模型实战指南
Dagger TypeScript SDK 详解安装、ESM 配置与 connect 连接模型实战指南【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/daggerDagger 的 TypeScript SDKnpm 包名dagger.io/dagger是你在 Node.js 项目中以 TypeScript/JavaScript 编写并执行 CI/CD 管道的官方客户端。本文基于仓库中 version-0.20 的 TypeScript SDK 参考文档结合 sdk/typescript 目录下的真实源码完整讲解 SDK 的安装方式、type: module与NodeNext等 ESM 强制配置的原因、connect/connection两个入口函数的连接机制与ConnectOpts参数以及 SDK 贡献者所需的npm link本地联调与watch编译流程读完即可在自己的 Node 项目中跑通 Dagger 管道并理解客户端与引擎的交互方式。什么是 Dagger TypeScript SDKDagger 官方文档将 SDK 定位为它包含了用 TypeScript 或 JavaScript 开发 CI/CD 管道所需的一切且这些管道可以运行在任何 OCI 兼容的容器运行时上。从 sdk/typescript/package.json 可以确认 SDK 的关键工程事实包名dagger.io/dagger模块类型type: module即以 ESMECMAScript Modules方式发布这是后文要求宿主项目同样设为 ESM 的根本原因运行环境engines: { node: 20 }即要求 Node 20 及以上版本导出入口exports字段暴露了.映射到./dist/src/index.js即主入口的类型声明位于./dist/src/index.d.ts和./telemetry映射到./dist/src/telemetry/index.js两个子路径遥测模块可以单独按需引入底层通信栈依赖graphql-request执行 GraphQL 查询、graphql/graphql-tag构造查询、grpc/grpc-jsgRPC 通道、node-fetchHTTP以及一组 OpenTelemetry 包opentelemetry/sdk-node、OTLP/Jaeger exporter 等说明客户端通过 GraphQL over 会话通道与 Dagger 引擎交互并内建分布式追踪能力。安装文档给出的标准安装命令是npm install dagger.io/dagger --save-dev安装后你就可以从包中导入connect等符号。从 sdk/typescript/src/index.ts 可以看到主入口的完整导出面export { GraphQLClient } from graphql-request // Telemetry export * from ./telemetry/index.js // Default client bindings export * from ./api/client.gen.js // Common errors export * from ./common/errors/index.js // Connection for library export type { CallbackFct } from ./connect.js export { connect, connection } from ./connect.js export type { ConnectOpts } from ./connectOpts.js // Export dagger connection context export { Context, BaseClient } from ./common/context.js // Module library export * from ./module/decorators.js export { entrypoint } from ./module/entrypoint/entrypoint.js export { getRegisteredClass } from ./module/registry.js由此可知 SDK 对外提供了四类能力connect/connection连接函数与ConnectOpts配置类型自动生成的 API 客户端绑定./api/client.gen.js即 DAGGER 核心 API 的 TypeScript 类型化方法链例如client.host()、client.container().from(...)等结构化错误类型./common/errors/包括DaggerSDKError、GraphQLRequestError、EngineSessionConnectionTimeoutError、NotAwaitedRequestError、ExecError等便于在管道中做细粒度错误处理模块开发支持./module/子系统的装饰器function、module、entrypoint等用于编写自定义 Dagger 模块而非仅调用核心 API。连接引擎connect 与 connectionSDK 与引擎的交互入口在 sdk/typescript/src/connect.ts 中实现提供了两个函数connect回调式 API 客户端export async function connect( cb: CallbackFct, config: ConnectOpts {}, ): Promisevoid其中CallbackFct的签名为(client: Client) Promisevoid。connect的内部流程是通过withGQLClient建立一个连接 Dagger 引擎的 GraphQL 客户端需要时自动拉起引擎会话见下文构造Connection与Context并创建自动生成的Client实例版本兼容性检查调用client.version()若不兼容会打印failed to check version compatibility警告——这解释了为什么 SDK 与 Dagger 引擎版本需要匹配将client交给你的回调函数执行具体管道逻辑。典型用法对应 sdk/typescript/src/connect.ts 的 JSDoc 示例风格import { connect } from dagger.io/dagger await connect(async (client) { const container await client .container() .from(alpine) .withExec([apk, add, curl]) .withExec([curl, https://dagger.io/]) })connection基于全局客户端connection接收一个无参异步函数使用 SDK 内置的全局 Dagger 客户端globalConnection执行并把执行包裹在 OpenTelemetry context 中做追踪传播结束时finally复位全局客户端并关闭遥测await connection(async () { // 使用全局 dag 客户端…… }, { LogOutput: process.stderr })ConnectOpts连接配置项ConnectOpts定义在 sdk/typescript/src/connectOpts.ts共三个可选字段字段类型说明Workdirstring覆盖 Dagger 工作目录默认process.cwd()LoadWorkspaceModulesboolean是否为该连接加载 workspace 模块默认只暴露核心 APILogOutputnode:stream的Writable开启日志输出可指向process.stdout/process.stderr等任意可写流引擎会话的建立与复用sdk/typescript/src/common/graphql/connect.ts 中的withGQLClient揭示了会话建立策略复用已有会话若环境变量DAGGER_SESSION_PORT已设置例如代码运行在dagger call或 dagger 引擎会话内部则必须同时提供DAGGER_SESSION_TOKEN缺失会直接抛错DAGGER_SESSION_TOKEN must be set if DAGGER_SESSION_PORT is set客户端直接以port token连接现有会话不再新起引擎自动供给provisioning否则动态import并调用 sdk/typescript/src/provisioning 的withEngineSession按需下载/启动本地引擎二进制并建立新会话失败时包装为failed to execute function with automatic provisioning错误。这也意味着 SDK 既可独立运行也能作为 Dagger 模块内部逻辑的一部分复用宿主会话避免重复拉起引擎。本地开发在自有 Node 项目中联调 SDK文档的“Local development”一节面向需要修改 SDK 源码、并在本地 Node 项目里直接测试的贡献者。以下四步完整继承原文档并补充仓库源码层面的解释。1. 创建新的 Node 项目已有 Node 项目可跳过此步mkdir my-test-ts-project # Init project (you may use yarn or pnpm) npm init -y # Add typescript npm install typescript ts-node --save-dev # Init typescript project npx tsc --init2. 更新项目配置为 ESM原文档强调Dagger 以type: module发布 SDK因此宿主项目的package.json必须设置相同的模块类型否则在 Node 的 CJS 上下文中会触发 ESM/CJS 导入错误。从项目根目录执行npm pkg set typemodule同时必须将tsconfig.json的module设为NodeNextmodule: NodeNext这个要求与 SDK 自身的编译配置一致sdk/typescript/tsconfig.json 中 SDK 使用module: Node16/moduleResolution: Node16、target: ES2022并开启emitDecoratorMetadata模块装饰器依赖。宿主项目采用NodeNext是与之配套的模块解析策略保证 ESM 导入含./xxx.js后缀写法行为一致。3. 通过 npm link 建立本地符号链接进入仓库中的 SDK 目录创建全局链接cd path/to/dagger/sdk/typescript # go into the package directory npm link # creates global link再回到你的业务项目目录链接安装该包cd path/to/my_app # go into your project directory. npm link dagger.io/dagger # link install the package此后对path/to/dagger/sdk/typescript的改动会实时反映在path/to/my_app/node_modules/dagger.io/dagger中实际指向 SDK 构建产物dist/目录。4. watch 模式编译开始贡献修改 SDK 源码期间应保持 watch 编译cd path/to/dagger/sdk/typescript # go into the package directory yarn watch # Recompile the code when input files are modified对照 sdk/typescript/package.json 的scripts字段可知watch实际执行的是tsc -w增量监听编译build则是普通的tsc测试脚本包括test:nodemocha与test:bunbun run --bun mocha。因此联调流程为一边yarn watch持续产出dist/一边在自己的项目里import { connect } from dagger.io/dagger即可像使用官方发布版一样导入本地 SDKimport { connect } from dagger.io/daggerSDK 的构建、测试与校验脚本速查在深入本地开发前熟悉 sdk/typescript/package.json 中的脚本有助于选择正确的验证手段脚本命令用途buildtsc一次性编译到dist/watchtsc -w监听源码变更并持续重编译test:node/test:bunmocha/bun run --bun mocha在 Node 或 Bun 运行时跑 mocha 测试lint/fmtyarn eslint ...ESLint 检查与自动修复docs:lint/docs:fmt对docs/current_docs下的.ts片段按eslint-docs.config.js校验保证官方文档中 TypeScript 示例与 SDK 真实类型一致值得注意的是docs:lint它用独立的 eslint-docs.config.js 对docs/current_docs中的.ts文档代码片段做类型级校验说明文档示例是被当成真实代码对待的这也是引用 SDK 行为时应优先以源码为准的原因。小结安装npm install dagger.io/dagger --save-dev要求 Node 20包以 ESM 发布type: module。连接connect提供回调式类型化客户端并做引擎版本检查connection使用全局客户端并内置 OTel 传播withGQLClient会优先复用DAGGER_SESSION_PORT/DAGGER_SESSION_TOKEN指定的既有会话否则自动供给新引擎会话。配置ConnectOpts支持Workdir默认process.cwd()、LoadWorkspaceModules、LogOutput三项。本地联调宿主项目必须npm pkg set typemodule且tsconfig.json使用NodeNext再用npm linkyarn watch实现源码级热替换开发。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考