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 TypeScript SDK 中CurrentModule类型的workdir方法的可选参数对象CurrentModuleWorkdirOpts展开讲解如何在 Dagger 模块函数执行期间从模块的 scratch 工作目录加载目录并通过exclude、include、gitignore三个选项精确控制要加载的产物范围。读完本文你将掌握模块工作目录的加载语义、过滤模式的用法以及它背后在 Dagger 引擎中的实现路径core/schema/module.go、core/directory.go。一、类型别名定义总览CurrentModuleWorkdirOpts是定义在 Dagger TypeScript SDK 客户端代码 sdk/typescript/src/api/client.gen.ts 中的一个类型别名其完整定义如下export type CurrentModuleWorkdirOpts { /** * 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 }它对应 Dagger GraphQL API 中currentModule.workdir字段的输入参数结构所有属性均为可选optional这意味着调用workdir(path)时可以完全不传选项也可以只传其中任意一个或多个。该类型所属的 API 分层如下文档导航路径见 README.md 与 modules.mddagger.io/dagger顶层包导出CurrentModule类api/client.gen子模块client.gen/README.md集中定义了所有由代码生成器产出的类型CurrentModuleWorkdirOpts就是其中之一。二、模块工作目录scratch working directory是什么在深入每个选项之前需要先理解workdir方法的语义。在 sdk/typescript/src/api/client.gen.ts 中workdir方法定义如下/** * Load a directory from the modules scratch working directory, including any changes that may have been made to it during module function execution. * param path Location of the directory to access (e.g., .). * param opts.exclude Exclude artifacts that match the given pattern (e.g., [node_modules/, .git*]). * param opts.include Include only artifacts that match the given pattern (e.g., [app/, package.*]). * param opts.gitignore Apply .gitignore filter rules inside the directory */ workdir (path: string, opts?: CurrentModuleWorkdirOpts): Directory { const ctx this._ctx.select(workdir, { path, ...opts }) return new Directory(ctx) }关键信息有两点加载目标模块的 scratch 工作目录scratch working directory并且包含模块函数执行期间对该目录所做的任何修改。这与CurrentModule.source()模块源码目录见 client.gen.ts不同——source()返回的是加载进引擎的模块源码目录可能包含生成的代码而workdir()面向的是运行时 scratch 目录。返回类型Directory因此可以继续链式调用 Dagger 目录 API如withDirectory、directory、export等进行进一步处理。引擎侧该字段注册于 core/schema/module.go对应解析函数为currentModuleWorkdir。三、三个可选属性逐一详解3.1 exclude排除匹配的产物属性类型必填说明excludestring[]否排除匹配给定模式的产物例如[node_modules/, .git*]exclude接收一组路径模式glob pattern所有匹配这些模式的目录或文件都会被排除在加载结果之外。典型场景是排除依赖目录与版本控制目录例如在加载工作目录中的项目代码时不希望把node_modules/或.git/一并带入 Dagger 的Directory快照。从引擎实现看exclude最终会传递到宿主机目录加载的exclude参数见下文第四节。CopyFilter.Exclude的默认值为空数组[]core/directory.go即默认不过滤任何内容。3.2 include仅包含匹配的产物属性类型必填说明includestring[]否只包含匹配给定模式的产物例如[app/, package.*]include与exclude相反采用白名单语义只有匹配给定模式的产物才会被加载。示例[app/, package.*]表示只加载app/目录以及以package.开头的文件如package.json、package-lock.json非常适合只关心工作目录中特定子集如单一子项目或配置文件的场景。同样CopyFilter.Include的默认值为[]core/directory.go即默认包含全部内容。提示从引擎实现看exclude与include是并列传入的过滤条件当两者同时给出时会依次作用于目录快照的复制过程。若你的目标只是排除若干内容用exclude若只想保留若干内容用include二者通常不需要同时使用。3.3 gitignore应用 .gitignore 过滤规则属性类型必填说明gitignoreboolean否在目录内部应用 .gitignore 过滤规则gitignore是一个布尔开关置为true时引擎会在加载目录时解析目标目录及其父目录内的.gitignore文件并自动跳过其中声明忽略的路径。CopyFilter.Gitignore的默认值为falsecore/directory.go即默认不启用 gitignore 规则。四、底层实现原理从 TypeScript 到引擎CurrentModuleWorkdirOpts的三个属性最终通过一段明确的调用链作用于目录加载理解这条链路有助于准确预期各选项的行为。4.1 workdir 解析函数引擎侧currentModuleWorkdir位于 core/schema/module.go其核心逻辑为func (s *moduleSchema) currentModuleWorkdir( ctx context.Context, curMod dagql.ObjectResult[*core.CurrentModule], args struct { Path string core.CopyFilter }, ) (inst dagql.Result[*core.Directory], err error) { // 1. 路径安全检查不允许逃逸 workdir if !filepath.IsLocal(args.Path) { return inst, fmt.Errorf(workdir path %q escapes workdir, args.Path) } // 2. 与运行时工作目录根路径拼接 args.Path filepath.Join(sdk.RuntimeWorkdirPath, args.Path) // 3. 委托给 host.directory透传 exclude / include / gitignore err dag.Select(ctx, dag.Root(), inst, dagql.Selector{Field: host}, dagql.Selector{ Field: directory, Args: []dagql.NamedInput{ {Name: path, Value: dagql.String(args.Path)}, {Name: exclude, Value: asArrayInput(args.Exclude, dagql.NewString)}, {Name: include, Value: asArrayInput(args.Include, dagql.NewString)}, {Name: gitignore, Value: dagql.Boolean(args.Gitignore)}, }, }, ) return inst, err }这段实现揭示了三个重要事实选项类型就是core.CopyFilterCurrentModuleWorkdirOpts的exclude/include/gitignore与引擎核心结构CopyFiltercore/directory.go一一对应type CopyFilter struct { Exclude []string default:[] Include []string default:[] Gitignore bool default:false }工作目录根路径为/scratchsdk.RuntimeWorkdirPath定义于 core/sdk/consts.go值为/scratch。因此调用workdir(.)实际加载的是宿主机上模块运行时 scratch 目录下拼接后的路径。路径安全约束filepath.IsLocal会拒绝../等包含父目录引用的路径防止访问越出 workdir 边界逃逸时会返回workdir path ... escapes workdir错误。4.2 host.directory 如何应用 gitignoreexclude/include/gitignore最终在host.directorycore/schema/host.go中生效。从 core/schema/host.go 的注释与代码可以看出 gitignore 的特殊处理逻辑if args.Gitignore { // 如果设置了 GitIgnoreRoot则以其为根加载 .gitignore 规则 // 否则向上搜索 .git 目录作为新的根 // 使 .gitignore 中的模式可以正确解析。 absRootCopyPath ... }也就是说当gitignore: true时引擎会以.git目录所在位置或显式指定的 git 根为基准重新确定复制根从而让.gitignore中通常相对仓库根书写的模式能够被正确解析随后会结合exclude/include的显式模式共同决定最终快照内容。hostDirectoryArgs中还包含FollowPaths等内部字段属于高级内部用法一般模块开发者无需关心。五、典型使用示例以下示例展示在 Dagger TypeScript 模块函数中如何使用CurrentModuleWorkdirOpts的三个选项基于 client.gen.ts 中的公开 API 签名组织可直接在模块中调用import { dag, Directory, object, func } from dagger.io/dagger object() class MyModule { /** * 加载模块工作目录中的全部内容但排除依赖目录与 git 元数据。 */ func() loadProject(project: Directory): Directory { // 读取模块函数执行期间写入 scratch 工作目录的产物 // 排除 node_modules 与所有 .git* 相关条目 return dag.currentModule().workdir(., { exclude: [node_modules/, .git*], }) } /** * 只加载工作目录中的应用子目录与 package 配置文件。 */ func() loadConfig(): Directory { return dag.currentModule().workdir(., { include: [app/, package.*], }) } /** * 依据 .gitignore 规则过滤后加载工作目录。 */ func() loadWithGitignore(): Directory { return dag.currentModule().workdir(., { gitignore: true, }) } }实际使用中workdir返回的Directory可以继续链式调用如.file(package.json)、.export(./out)、.withDirectory(...)与 Dagger 其他目录 API 完全一致。六、姊妹 APIworkdirFile与workdir配套的还有workdirFile方法client.gen.ts它从 scratch 工作目录加载单个文件而非整个目录/** * Load a file from the modules scratch working directory, including any changes that may have been made to it during module function execution. * param path Location of the file to retrieve (e.g., README.md). */ workdirFile (path: string): File { const ctx this._ctx.select(workdirFile, { path }) return new File(ctx) }引擎侧对应 core/schema/module.go 的currentModuleWorkdirFile它同样执行filepath.IsLocal路径安全检查、同样拼接RuntimeWorkdirPath但委托的是host.file而不是host.directory。由于目标是单个文件workdirFile不接收CurrentModuleWorkdirOpts选项。因此选择workdir还是workdirFile的判断标准很简单需要整目录快照可能还要继续做目录级操作用workdir只需要读取某个具体文件时用workdirFile更轻量。七、小结与注意事项选项类型默认值作用excludestring[][]排除匹配模式的产物如[node_modules/, .git*]includestring[][]仅保留匹配模式的产物如[app/, package.*]gitignorebooleanfalse应用.gitignore规则过滤目录内容使用时的几个要点默认不过滤三个选项全部省略时workdir加载 scratch 工作目录的完整快照。模式匹配exclude/include使用路径模式glob可同时覆盖目录node_modules/与文件.git*、package.*。路径安全path参数不允许包含..等越界引用引擎会拒绝逃逸 workdir 的请求core/schema/module.go。底层一致性TypeScript 层的CurrentModuleWorkdirOpts与引擎核心的core.CopyFilter结构一一对应理解该结构即可预测各 SDKGo、Python 等中同名参数的行为。运行时语义workdir加载的是模块函数执行期间的 scratch 目录含运行时修改与source()静态源码目录用途不同按需选择。通过合理组合这三个选项你可以精确控制模块工作目录快照的内容体积与范围避免将无关文件依赖目录、构建缓存、git 元数据带入下游的构建与测试流程从而提升缓存命中率与执行效率。【免费下载链接】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），仅供参考