Dagger TypeScript SDK 中 CurrentModuleWorkdirOpts 详解精准控制模块工作目录加载【免费下载链接】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导读在编写 Dagger 模块时模块函数执行期间会产生一个临时工作目录scratch working directory而CurrentModule.workdir()是模块代码在运行期重新加载该目录内容的唯一入口。本文以 Dagger 0.19 版 TypeScript SDK 的CurrentModuleWorkdirOpts类型为骨架系统讲解exclude、include、gitignore三个可选过滤选项的语义、默认值与使用场景并结合仓库源码GraphQL Schema 定义、引擎侧 Go 实现与生成的客户端代码剖析其底层工作原理帮助你写出可控、可复现的 Dagger 模块。一、类型定位workdir 方法的选项对象CurrentModuleWorkdirOpts是 TypeScript SDK 中CurrentModule.workdir(path, opts)方法的选项对象类型定义于 type-aliases/CurrentModuleWorkdirOpts.md。type CurrentModuleWorkdirOpts { exclude?: string[] gitignore?: boolean include?: string[] }三个属性全部可选意味着最简调用currentModule.workdir(.)即可工作过滤规则完全交给默认行为见下文 GraphQL Schema 的默认值。该方法本身的语义在生成的客户端代码中有明确注释sdk/typescript/src/api/client.gen.tsLoad a directory from the modules scratch working directory, including any changes that may have been made to it during module function execution.即从模块的临时工作目录加载一个目录包含模块函数执行期间对该目录做出的所有改动。这是与currentModule.source()只读的模块源码目录最关键的区别——workdir反映的是运行中的当前状态而非打包进模块的静态源码。二、三个选项逐一解析1.exclude?: string[]— 排除匹配模式的文件exclude?: string[]排除与给定模式匹配的构件artifacts。文档给出的典型示例为[node_modules/, .git*]该示例同时排除了整个node_modules目录与所有以.git开头的条目如.git、.gitignore、.gitattributes。常见用途加载工作目录时剔除依赖目录、构建产物、版本控制元数据避免将其带入后续的镜像构建或文件导出流程。2.include?: string[]— 只保留匹配模式的文件include?: string[]只包含与给定模式匹配的构件。文档示例[app/, package.*]该示例将加载范围收窄到app目录以及所有以package开头的文件如package.json、package-lock.json。典型场景工作目录中包含大量临时文件你只关心其中少数几个命名的源码/配置文件。使用提示exclude与include可以组合使用前者做黑名单过滤、后者做白名单筛选二者共同作用于最终的加载结果。若同时指定引擎会按两者规则的交集逻辑生成最终目录内容具体行为由底层CopyFilter处理详见下文。3.gitignore?: boolean— 应用 .gitignore 过滤规则gitignore?: boolean设置为true时会在加载目录的过程中应用该目录内的.gitignore过滤规则。这意味着你在.gitignore中声明忽略的文件例如日志、缓存、密钥等会被自动排除无需再通过exclude手动枚举。默认值为false不应用 .gitignore 规则。该选项与exclude的差异在于规则来源gitignore复用仓库既有的忽略清单exclude则由调用方按本次调用临时指定适合一次性的精细控制。三、源码级原理从 TypeScript 选项到引擎执行3.1 GraphQL Schema 层默认值与类型契约workdir字段在 GraphQL Schema 中的定义位于 core/schema/testdata/base_schema.graphqls Load a directory from the modules scratch working directory, including any changes that may have been made to it during module function execution. workdir( Location of the directory to access (e.g., .). path: String! Exclude artifacts that match the given pattern (e.g., [node_modules/, .git*]). exclude: [String!] [] Include only artifacts that match the given pattern (e.g., [app/, package.*]). include: [String!] [] Apply .gitignore filter rules inside the directory gitignore: Boolean false ): Directory!这里可以确认两个关键事实path是必填的字符串参数用于指定要访问的子目录位置如.exclude、include、gitignore三个选项在 Schema 层的默认值分别为[]、[]、false——与CurrentModuleWorkdirOpts中三者可选的属性定义完全对应。3.2 引擎侧实现路径安全校验与过滤透传真正执行加载逻辑的是moduleSchema.currentModuleWorkdir位于 core/schema/module.go。实现要点路径安全校验if !filepath.IsLocal(args.Path)会拒绝一切试图逃逸工作目录的路径如../并返回错误workdir path %q escapes workdir路径拼接args.Path filepath.Join(sdk.RuntimeWorkdirPath, args.Path)将请求的相对路径锚定到 SDK 运行时工作目录之下过滤透传三个选项被原样传递给host.directory查询——exclude、include转为字符串数组输入gitignore转为布尔输入最终由Directory的底层加载逻辑应用这些过滤规则。3.3 过滤规则的数据载体CopyFilterexclude/include/gitignore三个字段在引擎侧被统一封装为core.CopyFilter结构体定义于 core/directory.gotype CopyFilter struct { Exclude []string default:[] Include []string default:[] Gitignore bool default:false }CopyFilter.IsEmpty()方法在三个字段都为空时返回true引擎据此可以跳过不必要的过滤开销。从源码结构看该过滤器用于控制目录内容的拷贝/加载范围是workdir过滤能力在引擎层的直接数据载体。3.4 其他 SDK 的一致性同一组选项在其他语言的生成代码中保持完全一致的语义。例如 Go SDK 的生成代码 dagger.gen.go// CurrentModuleWorkdirOpts contains options for CurrentModule.Workdir type CurrentModuleWorkdirOpts struct { // Exclude artifacts that match the given pattern (e.g., [node_modules/, .git*]). Exclude []string // Include only artifacts that match the given pattern (e.g., [app/, package.*]). Include []string // Apply .gitignore filter rules inside the directory Gitignore bool }调用时仅将非零值参数写入 GraphQL 查询通过querybuilder.IsZeroValue判断保证了不传选项即不发送参数的按需传输行为。四、实战示例在模块函数中加载过滤后的工作目录假设你的模块函数在执行过程中向 scratch 工作目录写入了构建产物与临时文件现在需要把其中源码 应用配置的部分取出来用于后续步骤import { dag, Directory, CurrentModule } from dagger.io/dagger // 在模块函数内部 async function collectArtifacts(mod: CurrentModule): PromiseDirectory { return mod.workdir(., { // 排除依赖目录与版本控制元数据 exclude: [node_modules/, .git*, dist/cache/], // 只保留应用代码与清单文件 include: [src/, app/, package.*, tsconfig.json], // 额外应用 .gitignore 规则 gitignore: true, }) }当你不关心过滤、需要拿到完整的工作目录快照时直接省略选项对象即可const whole mod.workdir(.)如果需要读取单个文件而非整个目录可改用配套的workdirFile(path)方法sdk/typescript/src/api/client.gen.ts它返回File对象同样包含执行期间的变更。五、模式匹配语法要点exclude与include使用与常见 glob 一致的字符串模式以下规则有助于写出正确的过滤表达式目录模式以/结尾表示目录如node_modules/匹配整个目录树通配符*匹配任意字符序列如.git*匹配.git、.gitignore等所有以.git开头的条目package.*匹配package.json、package-lock.json等精确文件直接写文件名或路径段如tsconfig.json。建议在实际使用前先用小范围模式如单个目录验证过滤结果再逐步扩大避免因模式过宽而意外排除关键文件。总结CurrentModuleWorkdirOpts虽是一个仅有三个可选属性的类型别名却是 Dagger 模块运行时工作目录加载能力的关键控制面exclude负责剔除、include负责收窄、gitignore负责复用版本库忽略规则。通过 TypeScript SDK 的生成代码client.gen.ts、GraphQL Schemabase_schema.graphqls与引擎实现module.go三层证据链可以确认该选项最终会以CopyFilter的形式作用于host.directory的目录加载过程并且包含严格的路径逃逸防护。掌握这三个选项的组合用法即可在模块开发中精确、安全地控制工作目录内容的读取范围。【免费下载链接】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），仅供参考