Dagger TypeScript SDK API 详解ContainerWithDirectoryOpts 类型别名的五个写盘选项及其源码级行为【免费下载链接】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 v0.20 TypeScript SDK 参考文档中的ContainerWithDirectoryOpts类型别名为主线逐条解析exclude、include、gitignore、owner、expand五个选项的类型、语义与典型取值并结合当前仓库中sdk/typescript/src/api/client.gen.ts的生成代码与core/schema/container.go的 schema 定义说明该选项对象如何被Container.withDirectory方法消费、选项之间如何协同过滤写入容器的目录内容。读完后你可以直接照此在 TypeScript 模块中安全地把目录写入容器并理解每个选项对最终镜像层/容器文件系统产生的实际影响。一、ContainerWithDirectoryOpts 是什么在 ContainerWithDirectoryOpts.md 这份 v0.20 参考文档中ContainerWithDirectoryOpts被定义为一个对象类型别名Type AliasContainerWithDirectoryOptsobject它不是独立使用的类型而是Container类上withDirectory方法的第三个可选参数opts的形状描述。其作用是当你把一个Directory对象写入容器的指定路径时控制“写什么、以谁的身份写、路径如何解析”。在当前仓库的生成源码 client.gen.ts 中该类型的实际定义第 751–786 行与文档一一对应export type ContainerWithDirectoryOpts { /** * Patterns to exclude in the written directory (e.g. [node_modules/**, .gitignore, .git/]). */ exclude?: string[] /** * Patterns to include in the written directory (e.g. [*.go, go.mod, go.sum]). */ include?: string[] /** * Apply .gitignore rules when writing the directory. */ gitignore?: boolean /** * A user:group to set for the directory and its contents. * * The user and group can either be an ID (1000:1000) or a name (foo:bar). * * If the group is omitted, it defaults to the same as the user. */ owner?: string /** * Replace ${VAR} or $VAR in the value of path according to the current environment variables defined in the container (e.g. /$VAR/foo). */ expand?: boolean permissions?: number }可以看到所有字段都是optional即全部可省略省略时按引擎默认行为处理不做模式过滤、不套用 .gitignore 规则、不改所有权、路径不展开。二、五个核心选项逐一解析2.1 include 与 exclude白名单与黑名单字段类型含义include?string[]要包含进写入目录的模式列表例如[*.go, go.mod, go.sum]exclude?string[]要排除的模式列表例如[node_modules/**, .gitignore, .git/]两者都是 glob 风格模式数组分别控制写入容器的目录中“保留什么”和“丢弃什么”include是白名单语义只写入匹配任一模式的条目exclude是黑名单语义写入时跳过匹配任一模式的条目。文档给出的官方示例非常典型拷贝 Go 项目时include: [*.go, go.mod, go.sum]拷贝前端项目时exclude: [node_modules/**, .gitignore, .git/]避免把依赖目录和版本库元数据写进容器层。2.2 gitignore复用 .gitignore 规则gitignore?: boolean—— “Apply .gitignore rules when writing the directory.”设为true时写入目录前会套用源目录中的.gitignore规则来过滤文件。这对“把 Git 工作区内容作为上下文写进容器”的场景特别有用Git 认为应忽略的构建产物、日志、缓存在写入容器时同样被跳过无需手工维护一份exclude列表。2.3 owner写入后的属主owner?: string的格式为user:group用户与组都支持ID 形式1000:1000或名字形式foo:bar若省略组名如owner: foo组默认与用户相同该属主会应用到“目录及其全部内容”。一个常用写法是owner: 1000:1000保证写入的文件属主与运行阶段的非 root 用户一致避免后续withExec以该用户执行命令时出现权限拒绝。2.4 expand按容器环境变量展开路径expand?: boolean—— “Replace${VAR}or$VARin the value of path according to the current environment variables defined in the container (e.g./$VAR/foo)”。启用后path参数本身可以携带环境变量占位符比如先用withEnvVariable(APP_DIR, /opt/app)设置环境变量再withDirectory(/$APP_DIR/data, source, { expand: true })。这使写入目标路径可以复用容器内已定义的配置而不是在模块代码里硬编码。2.5 与同类 Opts 的区分withDirectory在多个对象上重载出现但选项类型各不相同不要混用Container.withDirectory使用ContainerWithDirectoryOpts本文主题Directory.withDirectory使用DirectoryWithDirectoryOpts见同目录文档 DirectoryWithDirectoryOpts.md其字段侧重permissions等目录级权限设置Workspace.withDirectory无 opts 参数直接withDirectory(path, source)。在 client.gen.ts 中可以同时看到这三处重载Container类约在第 5866 行、Directory类约在第 7168 行、Workspace类约在第 16704 行。三、调用位置Container.withDirectory 如何消费 optsContainerWithDirectoryOpts的唯一消费点是Container类的withDirectory方法。当前仓库生成代码client.gen.ts如下/** * Return a new container snapshot, with a directory added to its filesystem * param path Location of the written directory (e.g., /tmp/directory). * param source Identifier of the directory to write * param opts.exclude Patterns to exclude in the written directory (e.g. [node_modules/**, .gitignore, .git/]). * param opts.include Patterns to include in the written directory (e.g. [*.go, go.mod, go.sum]). * param opts.gitignore Apply .gitignore rules when writing the directory. * param opts.owner A user:group to set for the directory and its contents. * param opts.inheritOwner Set the owner to the containers current user. * param opts.expand Replace ${VAR} or $VAR in the value of path according to the current environment variables defined in the container (e.g. /$VAR/foo). */ withDirectory ( path: string, source: Directory, opts?: ContainerWithDirectoryOpts, ): Container { const ctx this._ctx.select(withDirectory, { path, source, ...opts }) return new Container(ctx) }三个要点返回新的Container快照withDirectory不修改原容器而是基于当前状态派生新对象——这是 Dagger 不可变immutableDAG 模型的直接体现opts 被展开进选择上下文{ path, source, ...opts }会把选项平铺为withDirectory字段调用的参数对应 GraphQL schema 中的withDirectory字段由引擎在求值时执行实际的目录写入参数顺序固定path是写入位置如/tmp/directorysource是被写入的Directory对象opts为可选过滤/属主配置。从源码结构看SDK 侧仅做参数打包this._ctx.select(...)真正的 glob 过滤、gitignore 套用、属主设置发生在引擎端引擎侧的字段定义可参见 core/schema/container.go其中withDirectory相关字段的inheritOwner参数带有View(AfterVersion(v1.0.0-0))的版本门控说明部分选项是随版本逐步加入 schema 的——阅读参考文档时应留意文档所对应的 SDK 版本。四、实战示例写入目录并组合多个选项import { dagger, Directory } from dagger.io/dagger const client await dagger.connect() // 1. 准备一个目录对象例如从 Git 仓库取源码树 const repo client.git(https://example.com/team/app.git).branch(main).clone() const source repo.tree() // 2. 写入容器白名单 属主 路径变量展开组合使用 const app client .host() .container() .withEnvVariable(APP_DIR, /opt/app) .withDirectory( /$APP_DIR/src, // path配合 expand 展开 source, { include: [*.ts, package.json, package-lock.json], exclude: [node_modules/**], gitignore: true, owner: 1000:1000, expand: true, }, // ContainerWithDirectoryOpts ) // 3. 在写入之后以该目录工作 const result await app .withWorkdir(/opt/app/src) .withExec([node, --version]) .stdout()该示例覆盖了文档定义的全部五个选项include/exclude控制内容范围gitignore: true叠加.gitignore过滤owner把写入内容属主设为1000:1000expand: true让path中的$APP_DIR在求值时替换为环境变量值。需要注意的适用前提path必须是容器内绝对路径include与exclude同时给出时过滤语义由引擎按两者共同作用决定建议不要同时指定相互矛盾的模式集合owner使用名字形式时名字必须在容器文件系统可解析基础镜像中存在对应用户/组使用 ID 形式则无此依赖。五、相关类型与深入阅读ContainerWithDirectoryOpts属于api/client.gen下client.gen.ts生成的一组 “With*Opts” 选项类型之一同类文档与源码位置如下均位于 client.gen.ts 或版本化文档 type-aliases 目录 内写单个文件ContainerWithFileOpts.md对应Container.withFile移除目录ContainerWithoutDirectoryOpts.md对应Container.withoutDirectory目录自身写目录DirectoryWithDirectoryOpts.md所有权相关的引擎端集成测试InheritOwner等属主行为的验证方式见 core/integration/container_test.go 与 core/integration/ownership_test.go。小结ContainerWithDirectoryOpts虽然只是一个对象类型别名但它集中了“把目录写进容器”这一高频操作的全部控制面——内容过滤include/exclude/gitignore、属主owner、路径解析expand。理解其字段后可直接对照 client.gen.ts 的类型定义与withDirectory方法实现在模块代码中编写可复制、可复现的容器构建步骤。【免费下载链接】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 API 详解：ContainerWithDirectoryOpts 类型别名的五个写盘选项及其源码级行为
Dagger TypeScript SDK API 详解ContainerWithDirectoryOpts 类型别名的五个写盘选项及其源码级行为【免费下载链接】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 v0.20 TypeScript SDK 参考文档中的ContainerWithDirectoryOpts类型别名为主线逐条解析exclude、include、gitignore、owner、expand五个选项的类型、语义与典型取值并结合当前仓库中sdk/typescript/src/api/client.gen.ts的生成代码与core/schema/container.go的 schema 定义说明该选项对象如何被Container.withDirectory方法消费、选项之间如何协同过滤写入容器的目录内容。读完后你可以直接照此在 TypeScript 模块中安全地把目录写入容器并理解每个选项对最终镜像层/容器文件系统产生的实际影响。一、ContainerWithDirectoryOpts 是什么在 ContainerWithDirectoryOpts.md 这份 v0.20 参考文档中ContainerWithDirectoryOpts被定义为一个对象类型别名Type AliasContainerWithDirectoryOptsobject它不是独立使用的类型而是Container类上withDirectory方法的第三个可选参数opts的形状描述。其作用是当你把一个Directory对象写入容器的指定路径时控制“写什么、以谁的身份写、路径如何解析”。在当前仓库的生成源码 client.gen.ts 中该类型的实际定义第 751–786 行与文档一一对应export type ContainerWithDirectoryOpts { /** * Patterns to exclude in the written directory (e.g. [node_modules/**, .gitignore, .git/]). */ exclude?: string[] /** * Patterns to include in the written directory (e.g. [*.go, go.mod, go.sum]). */ include?: string[] /** * Apply .gitignore rules when writing the directory. */ gitignore?: boolean /** * A user:group to set for the directory and its contents. * * The user and group can either be an ID (1000:1000) or a name (foo:bar). * * If the group is omitted, it defaults to the same as the user. */ owner?: string /** * Replace ${VAR} or $VAR in the value of path according to the current environment variables defined in the container (e.g. /$VAR/foo). */ expand?: boolean permissions?: number }可以看到所有字段都是optional即全部可省略省略时按引擎默认行为处理不做模式过滤、不套用 .gitignore 规则、不改所有权、路径不展开。二、五个核心选项逐一解析2.1 include 与 exclude白名单与黑名单字段类型含义include?string[]要包含进写入目录的模式列表例如[*.go, go.mod, go.sum]exclude?string[]要排除的模式列表例如[node_modules/**, .gitignore, .git/]两者都是 glob 风格模式数组分别控制写入容器的目录中“保留什么”和“丢弃什么”include是白名单语义只写入匹配任一模式的条目exclude是黑名单语义写入时跳过匹配任一模式的条目。文档给出的官方示例非常典型拷贝 Go 项目时include: [*.go, go.mod, go.sum]拷贝前端项目时exclude: [node_modules/**, .gitignore, .git/]避免把依赖目录和版本库元数据写进容器层。2.2 gitignore复用 .gitignore 规则gitignore?: boolean—— “Apply .gitignore rules when writing the directory.”设为true时写入目录前会套用源目录中的.gitignore规则来过滤文件。这对“把 Git 工作区内容作为上下文写进容器”的场景特别有用Git 认为应忽略的构建产物、日志、缓存在写入容器时同样被跳过无需手工维护一份exclude列表。2.3 owner写入后的属主owner?: string的格式为user:group用户与组都支持ID 形式1000:1000或名字形式foo:bar若省略组名如owner: foo组默认与用户相同该属主会应用到“目录及其全部内容”。一个常用写法是owner: 1000:1000保证写入的文件属主与运行阶段的非 root 用户一致避免后续withExec以该用户执行命令时出现权限拒绝。2.4 expand按容器环境变量展开路径expand?: boolean—— “Replace${VAR}or$VARin the value of path according to the current environment variables defined in the container (e.g./$VAR/foo)”。启用后path参数本身可以携带环境变量占位符比如先用withEnvVariable(APP_DIR, /opt/app)设置环境变量再withDirectory(/$APP_DIR/data, source, { expand: true })。这使写入目标路径可以复用容器内已定义的配置而不是在模块代码里硬编码。2.5 与同类 Opts 的区分withDirectory在多个对象上重载出现但选项类型各不相同不要混用Container.withDirectory使用ContainerWithDirectoryOpts本文主题Directory.withDirectory使用DirectoryWithDirectoryOpts见同目录文档 DirectoryWithDirectoryOpts.md其字段侧重permissions等目录级权限设置Workspace.withDirectory无 opts 参数直接withDirectory(path, source)。在 client.gen.ts 中可以同时看到这三处重载Container类约在第 5866 行、Directory类约在第 7168 行、Workspace类约在第 16704 行。三、调用位置Container.withDirectory 如何消费 optsContainerWithDirectoryOpts的唯一消费点是Container类的withDirectory方法。当前仓库生成代码client.gen.ts如下/** * Return a new container snapshot, with a directory added to its filesystem * param path Location of the written directory (e.g., /tmp/directory). * param source Identifier of the directory to write * param opts.exclude Patterns to exclude in the written directory (e.g. [node_modules/**, .gitignore, .git/]). * param opts.include Patterns to include in the written directory (e.g. [*.go, go.mod, go.sum]). * param opts.gitignore Apply .gitignore rules when writing the directory. * param opts.owner A user:group to set for the directory and its contents. * param opts.inheritOwner Set the owner to the containers current user. * param opts.expand Replace ${VAR} or $VAR in the value of path according to the current environment variables defined in the container (e.g. /$VAR/foo). */ withDirectory ( path: string, source: Directory, opts?: ContainerWithDirectoryOpts, ): Container { const ctx this._ctx.select(withDirectory, { path, source, ...opts }) return new Container(ctx) }三个要点返回新的Container快照withDirectory不修改原容器而是基于当前状态派生新对象——这是 Dagger 不可变immutableDAG 模型的直接体现opts 被展开进选择上下文{ path, source, ...opts }会把选项平铺为withDirectory字段调用的参数对应 GraphQL schema 中的withDirectory字段由引擎在求值时执行实际的目录写入参数顺序固定path是写入位置如/tmp/directorysource是被写入的Directory对象opts为可选过滤/属主配置。从源码结构看SDK 侧仅做参数打包this._ctx.select(...)真正的 glob 过滤、gitignore 套用、属主设置发生在引擎端引擎侧的字段定义可参见 core/schema/container.go其中withDirectory相关字段的inheritOwner参数带有View(AfterVersion(v1.0.0-0))的版本门控说明部分选项是随版本逐步加入 schema 的——阅读参考文档时应留意文档所对应的 SDK 版本。四、实战示例写入目录并组合多个选项import { dagger, Directory } from dagger.io/dagger const client await dagger.connect() // 1. 准备一个目录对象例如从 Git 仓库取源码树 const repo client.git(https://example.com/team/app.git).branch(main).clone() const source repo.tree() // 2. 写入容器白名单 属主 路径变量展开组合使用 const app client .host() .container() .withEnvVariable(APP_DIR, /opt/app) .withDirectory( /$APP_DIR/src, // path配合 expand 展开 source, { include: [*.ts, package.json, package-lock.json], exclude: [node_modules/**], gitignore: true, owner: 1000:1000, expand: true, }, // ContainerWithDirectoryOpts ) // 3. 在写入之后以该目录工作 const result await app .withWorkdir(/opt/app/src) .withExec([node, --version]) .stdout()该示例覆盖了文档定义的全部五个选项include/exclude控制内容范围gitignore: true叠加.gitignore过滤owner把写入内容属主设为1000:1000expand: true让path中的$APP_DIR在求值时替换为环境变量值。需要注意的适用前提path必须是容器内绝对路径include与exclude同时给出时过滤语义由引擎按两者共同作用决定建议不要同时指定相互矛盾的模式集合owner使用名字形式时名字必须在容器文件系统可解析基础镜像中存在对应用户/组使用 ID 形式则无此依赖。五、相关类型与深入阅读ContainerWithDirectoryOpts属于api/client.gen下client.gen.ts生成的一组 “With*Opts” 选项类型之一同类文档与源码位置如下均位于 client.gen.ts 或版本化文档 type-aliases 目录 内写单个文件ContainerWithFileOpts.md对应Container.withFile移除目录ContainerWithoutDirectoryOpts.md对应Container.withoutDirectory目录自身写目录DirectoryWithDirectoryOpts.md所有权相关的引擎端集成测试InheritOwner等属主行为的验证方式见 core/integration/container_test.go 与 core/integration/ownership_test.go。小结ContainerWithDirectoryOpts虽然只是一个对象类型别名但它集中了“把目录写进容器”这一高频操作的全部控制面——内容过滤include/exclude/gitignore、属主owner、路径解析expand。理解其字段后可直接对照 client.gen.ts 的类型定义与withDirectory方法实现在模块代码中编写可复制、可复现的容器构建步骤。【免费下载链接】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），仅供参考