Dagger TypeScript SDK 中 DirectoryFilterOpts 类型别名详解用 include / exclude / gitignore 精准裁剪目录快照【免费下载链接】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 0.21 版本 TypeScript SDK 参考文档中的DirectoryFilterOpts类型别名展开系统讲解该类型的三个可选属性include、exclude、gitignore的语义、glob 匹配规则与组合用法并结合仓库源码剖析Directory.filter从 SDK 层到 GraphQL 层再到引擎层CopyFilter/ layercopy的完整调用链。读完本文你将能够在 Dagger 管道中精准地裁剪目录快照——无论是剔除node_modules与密钥文件还是只保留指定子目录与清单文件都能以最小代价、可验证的方式落地。DirectoryFilterOpts 是什么DirectoryFilterOpts是 Dagger TypeScript SDK 中为Directory.filter方法即DirectoryID.filterGraphQL 字段提供的选项对象类型。它的定义位于版本化文档目录 DirectoryFilterOpts.md对应生成代码 client.gen.ts 中的export type DirectoryFilterOpts { exclude?: string[] gitignore?: boolean include?: string[] }它本身是一个 TypeScriptobject类型别名所有属性均为可选。调用的本质是对目录做一次“快照过滤”生成一个仅包含或剔除部分路径的新目录快照原目录不变不可变快照模型。该类型被Directory.filter方法消费方法签名与实现见 client.gen.tsfilter (opts?: DirectoryFilterOpts): Directory { const ctx this._ctx.select(filter, { ...opts }) return new Directory(ctx) }可以看到选项对象被原样展开为 GraphQL 查询参数通过_ctx.select(filter, ...)构建惰性查询节点最终返回一个新的Directory对象——这就是 Dagger 典型的“声明式、惰性求值”调用方式此处只是登记操作真正的过滤在引擎执行查询时才发生。三个可选属性详解exclude排除匹配 glob 的路径类型string[]含义设置后匹配其中任一 glob 模式的路径会被从新快照中排除。文档示例[node_modules/, .git*, .env]常见用法是过滤掉依赖目录、版本控制目录和敏感文件。注意 glob 语义node_modules/带尾部斜杠表示目录.git*覆盖.git目录及.gitignore等衍生文件.env用于剔除密钥/环境配置文件。include仅保留匹配 glob 的路径类型string[]含义设置后只有匹配其中任一 glob 模式的路径会被保留进新快照其余一律剔除。文档示例[app/, package.*]典型场景是“白名单式”提取只把应用源码目录与包清单拷进构建上下文例如[app/, package.*]会保留app/目录及其全部子内容以及package.json、package-lock.json这类以package.开头的文件。gitignore应用 .gitignore 规则类型boolean含义为true时过滤过程会读取目录内的.gitignore规则并据此排除匹配路径。相当于把仓库已声明“不该提交”的内容构建产物、缓存、本地配置一并排除省去手工罗列exclude模式。组合语义与匹配规则三者皆可组合include与exclude同时给出时先按include圈定候选集合再以exclude剔除其中命中的路径gitignore与exclude的命中结果共同参与剔除。全部省略时的行为三个属性都缺省时过滤器为空操作——引擎层对空过滤器的判定见 core/directory.go 的CopyFilter.IsEmpty()仅当exclude、include均无元素且gitignore为false时返回true此时filter退化为返回原目录可推断IsEmpty是底层跳过过滤逻辑的判据。glob 为空串或以!开头从底层解析看空模式与取反模式会被跳过不会参与匹配见 core/directory.goresolveAttemptUnpackMatches中if includePattern || strings.HasPrefix(includePattern, !)的守卫逻辑。底层实现从 TypeScript 到引擎的调用链1. TypeScript SDK 层生成代码 client.gen.ts 中filter方法的 JSDoc 注释与文档完全一致属性名通过{ ...opts }直接映射为 GraphQL 参数。2. GraphQL Schema 层core/schema在 core/schema/directory.go 中Directory.filter被声明为 dagql 节点函数三个参数分别带文档注释dagql.NodeFunc(filter, maintainContentHashing(s.filter)). Doc(Return a snapshot with some paths included or excluded). Args( dagql.Arg(exclude).Doc(If set, paths matching one of these glob patterns is excluded from the new snapshot. Example: [node_modules/, .git*, .env]), dagql.Arg(include).Doc(If set, only paths matching one of these glob patterns is included in the new snapshot. Example: (e.g., [app/, package.*]).), dagql.Arg(gitignore).Doc(If set, apply .gitignore rules when filtering the directory.), )Schema 层的filter实现core/schema/directory.go把三个参数打包为FilterArgs内嵌core.CopyFilter再以exclude/include/gitignore命名输入的方式转发给内部目录节点——这也解释了为何参数在 GraphQL 中同名可见。3. 引擎层core.CopyFilter真正承载过滤语义的是核心结构体 core/directory.gotype CopyFilter struct { Exclude []string default:[] Include []string default:[] Gitignore bool default:false }CopyFilter同时被Directory.WithDirectorycore/directory.go等复制类操作复用说明“include/exclude/gitignore”是一套跨 API 统一的过滤原语filter是它的独立入口withDirectory合并目录时也走同一套匹配逻辑。4. 测试佐证core/schema/workspace_test.go 中的TestWorkspaceFilterWithDirectoryArgs构造core.CopyFilter{Include: []string{app/**}, Exclude: []string{.git}}断言生成的 dagql 参数依次为path、source、include、exclude——证实include/exclude的透传关系与参数顺序可作为阅读实现时的对照样例。实战示例在 Dagger 管道中过滤目录以下示例展示如何结合 Dagger 的host.directory、Directory.filter与container.withDirectory构建一个“只带源码、不带噪音”的构建上下文import { dag, Directory } from dagger.io/dagger // 1. 读取主机目录本地仓库根 const src dag.host().directory(.) // 2. 过滤只保留 app/ 与 package.*同时剔除 node_modules 与 .git* const filtered: Directory src.filter({ include: [app/, package.*], exclude: [node_modules/, .git*, .env], }) // 3. 若目录内有 .gitignore可直接声明式启用其规则 const withGitignore: Directory src.filter({ gitignore: true, exclude: [.env], }) // 4. 将过滤后的目录作为构建上下文挂载进容器 const ctr dag .container() .from(node:22-alpine) .withDirectory(/work, filtered) .withWorkdir(/work)要点回顾filter是惰性声明返回新的Directory不会修改原目录单一include场景下快照只含匹配项白名单exclude与gitignore负责黑名单剔除过滤结果可直接交给Container.withDirectory、Directory.export或作为后续缓存键参与哈希Schema 层以maintainContentHashing包装filter保证内容哈希稳定性该类型同样适用于withDirectory场景中的DirectoryWithDirectoryOpts其 Go 运行时对应结构见 dagger.gen.go同一套过滤语义可复用于目录合并。相关文档与进一步阅读类型别名官方参考DirectoryFilterOpts.mdTypeScript SDK 生成代码中Directory.filter的实现与 JSDocclient.gen.tsGraphQL Schema 层filter节点定义与实现core/schema/directory.go引擎层过滤原语CopyFilter及其判空逻辑core/directory.go过滤参数透传的测试样例core/schema/workspace_test.go【免费下载链接】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），仅供参考