Dagger TypeScript SDK 的 ContainerDirectoryOpts 详解用 expand 选项动态解析容器目录路径【免费下载链接】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 的Container.directory()方法用于从容器根文件系统中取回某个目录挂载点也包含在内。ContainerDirectoryOpts正是该方法的选项类型其唯一可选属性expand允许路径中的${VAR}/$VAR占位符按容器内部的环境变量进行动态替换。本文基于 Dagger 0.19 版本的 API 参考文档与仓库源码完整讲解该类型别名的定义、底层实现原理与实战用法。类型别名定义速览在 TypeScript SDK 中该类型定义于 sdk/typescript/src/api/client.gen.ts原始 API 参考文档位于 docs/versioned_docs/version-0.19/reference/typescript/api/client.gen/type-aliases/ContainerDirectoryOpts.mdexport type ContainerDirectoryOpts { /** * 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 }属性类型必填默认值说明expandboolean否false按容器当前环境变量替换path中的${VAR}或$VAR例如/$VAR/foo它作为一个object类型别名存在作为Container.directory方法的第二参数传入。在 SDK 客户端中其典型使用形态如下见 sdk/typescript/src/api/client.gen.tsdirectory (path: string, opts?: ContainerDirectoryOpts): Directory { const ctx this._ctx.select(directory, { path, ...opts }) return new Directory(ctx) }该方法的 GraphQL 语义在核心 Schema 中定义见 core/schema/container.godirectory(path, expand)从容器根文件系统取回目录且挂载点Mounts包含在内。expand 参数动态路径的两种占位符语法expand的核心能力是当容器镜像或构建链中已通过withEnvVariable设置了环境变量时允许你在path参数中引用它们引擎会在解析路径前完成替换。支持两种书写形式${VAR}花括号形式适合变量名与相邻字符需要明确分隔的场景$VAR裸变量形式例如/$VAR/foo。一个直观的对比// 不使用 expand路径按字面量解析会查找名为 $HOME 的目录 const d1 ctr.directory(/$HOME/work) // 使用 expand$HOME 被替换为容器内环境变量的实际值 const d2 ctr.directory(/$HOME/work, { expand: true })实际替换发生在引擎执行前。核心 Schema 将参数建模为见 core/schema/container.gotype containerDirectoryArgs struct { Path string Expand bool default:false }注意default:false——即使调用方未显式传入expand其值也为false路径保持字面量不变。底层实现expandEnvVar 的解析流程在 core/schema/container.go 中directory解析器首先对路径做展开再基于容器的WorkingDir计算绝对路径path, err : expandEnvVar(ctx, parent.Self(), args.Path, args.Expand) if err ! nil { return dagql.ObjectResult[*core.Directory]{}, err } resolvedPath : absPath(parent.Self().Config.WorkingDir, path)expandEnvVar见 core/schema/container.go的实现要点如下若expand为false直接原样返回输入路径若为true先读取容器的镜像配置parent.ImageConfig取得当前环境变量集合调用 Go 标准库的os.Expand对${VAR}/$VAR进行替换变量值来自容器自身的cfg.Env替换完成后路径再经absPath(workingDir, path)解析为绝对路径然后构造core.Directory返回。这意味着展开语义严格以容器内的环境变量为准而不是宿主机的环境变量——这正是它适合做“镜像内构建产物路径”动态寻址的原因。实战示例结合测试用例的完整用法仓库集成测试 core/integration/container_test.go 中的TestEnvExpand子测试给出了ContainerDirectoryOpts最直接的用法示例const ctr client .container() .from(alpine:latest) .withEnvVariable(foo, bar) .withDirectory( /some-path/bar, client.directory().withNewFile(/some-file.txt, contents in foo file), ) // 关键以容器内环境变量 foo 动态解析目录路径 const contents await ctr .directory(/some-path/${foo}, { expand: true }) .file(some-file.txt) .contents() // contents contents in foo file在该测试中写入目录时使用了字面量路径/some-path/bar读取时则通过${foo}foobar动态指向同一目录从而验证了“写入路径与读取路径解耦”的能力。同时expand还可以配合写入侧使用。测试 core/integration/container_test.go 展示了对称的写入场景const output await client .container() .from(alpine:latest) .withEnvVariable(foo, bar) .withDirectory( /some-path/${foo}, // 写入时展开 client.directory().withNewFile(/some-file.txt, contents in foo file), { expand: true }, ) .directory(/some-path/bar, { expand: true }) // 读取时展开 .file(some-file.txt) .contents()使用限制secret 与 volatile 变量不可展开expandEnvVar在展开前会收集容器内的两类特殊变量并明确拒绝展开见 core/schema/container.go通过withSecretVariable注入的密钥环境变量通过withVolatileVariable注入的易变volatile环境变量。一旦path中引用了它们引擎会返回形如expand cannot be used with secret env variable GITEA_TOKEN或expand cannot be used with volatile env variable RUN_ID的错误。对应测试见 core/integration/container_test.gosecret与 core/integration/container_test.govolatile。这样设计是为了避免密钥值被意外写入路径 / 缓存键以及防止每次运行都可能变化的 volatile 值破坏构建缓存的可复现性。若变量未在容器环境中定义os.Expand会将其替换为空字符串这一点在使用时需要留意。与相关 API 的一致性expand并非directory独有它是 Dagger Container API 中路径型参数的通用能力同类选项包括ContainerWithDirectoryOpts.expandwithDirectory写入目录时展开路径ContainerFileOpts.expand/ContainerWithFileOpts.expandfile/withFile取回与写入文件时展开ContainerWithNewFileOpts.expand、ContainerWithoutDirectoryOpts.expand、ContainerWithMountedDirectoryOpts.expand等覆盖新建文件、删除目录、挂载目录等场景。在 core/integration/container_test.go 的TestEnvExpand中以上场景均有对应测试用例验证。这意味着你可以在构建流水线中统一采用“环境变量驱动路径”的约定先withEnvVariable定义构建产物路径如BUILD_DIR/out/release再在所有文件系统操作处配合{ expand: true }引用从而避免在多个调用点重复硬编码路径字符串。小结ContainerDirectoryOpts结构简单但语义明确通过expand布尔选项Container.directory()可以按容器内环境变量动态解析目录路径支持$VAR与${VAR}两种语法配合withEnvVariable可以显著提升 Dagger 流水线中路径参数的可维护性。使用时需牢记两点展开针对容器环境而非宿主机环境secret 与 volatile 变量被明确禁止用于展开。【免费下载链接】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 的 ContainerDirectoryOpts 详解：用 expand 选项动态解析容器目录路径
Dagger TypeScript SDK 的 ContainerDirectoryOpts 详解用 expand 选项动态解析容器目录路径【免费下载链接】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 的Container.directory()方法用于从容器根文件系统中取回某个目录挂载点也包含在内。ContainerDirectoryOpts正是该方法的选项类型其唯一可选属性expand允许路径中的${VAR}/$VAR占位符按容器内部的环境变量进行动态替换。本文基于 Dagger 0.19 版本的 API 参考文档与仓库源码完整讲解该类型别名的定义、底层实现原理与实战用法。类型别名定义速览在 TypeScript SDK 中该类型定义于 sdk/typescript/src/api/client.gen.ts原始 API 参考文档位于 docs/versioned_docs/version-0.19/reference/typescript/api/client.gen/type-aliases/ContainerDirectoryOpts.mdexport type ContainerDirectoryOpts { /** * 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 }属性类型必填默认值说明expandboolean否false按容器当前环境变量替换path中的${VAR}或$VAR例如/$VAR/foo它作为一个object类型别名存在作为Container.directory方法的第二参数传入。在 SDK 客户端中其典型使用形态如下见 sdk/typescript/src/api/client.gen.tsdirectory (path: string, opts?: ContainerDirectoryOpts): Directory { const ctx this._ctx.select(directory, { path, ...opts }) return new Directory(ctx) }该方法的 GraphQL 语义在核心 Schema 中定义见 core/schema/container.godirectory(path, expand)从容器根文件系统取回目录且挂载点Mounts包含在内。expand 参数动态路径的两种占位符语法expand的核心能力是当容器镜像或构建链中已通过withEnvVariable设置了环境变量时允许你在path参数中引用它们引擎会在解析路径前完成替换。支持两种书写形式${VAR}花括号形式适合变量名与相邻字符需要明确分隔的场景$VAR裸变量形式例如/$VAR/foo。一个直观的对比// 不使用 expand路径按字面量解析会查找名为 $HOME 的目录 const d1 ctr.directory(/$HOME/work) // 使用 expand$HOME 被替换为容器内环境变量的实际值 const d2 ctr.directory(/$HOME/work, { expand: true })实际替换发生在引擎执行前。核心 Schema 将参数建模为见 core/schema/container.gotype containerDirectoryArgs struct { Path string Expand bool default:false }注意default:false——即使调用方未显式传入expand其值也为false路径保持字面量不变。底层实现expandEnvVar 的解析流程在 core/schema/container.go 中directory解析器首先对路径做展开再基于容器的WorkingDir计算绝对路径path, err : expandEnvVar(ctx, parent.Self(), args.Path, args.Expand) if err ! nil { return dagql.ObjectResult[*core.Directory]{}, err } resolvedPath : absPath(parent.Self().Config.WorkingDir, path)expandEnvVar见 core/schema/container.go的实现要点如下若expand为false直接原样返回输入路径若为true先读取容器的镜像配置parent.ImageConfig取得当前环境变量集合调用 Go 标准库的os.Expand对${VAR}/$VAR进行替换变量值来自容器自身的cfg.Env替换完成后路径再经absPath(workingDir, path)解析为绝对路径然后构造core.Directory返回。这意味着展开语义严格以容器内的环境变量为准而不是宿主机的环境变量——这正是它适合做“镜像内构建产物路径”动态寻址的原因。实战示例结合测试用例的完整用法仓库集成测试 core/integration/container_test.go 中的TestEnvExpand子测试给出了ContainerDirectoryOpts最直接的用法示例const ctr client .container() .from(alpine:latest) .withEnvVariable(foo, bar) .withDirectory( /some-path/bar, client.directory().withNewFile(/some-file.txt, contents in foo file), ) // 关键以容器内环境变量 foo 动态解析目录路径 const contents await ctr .directory(/some-path/${foo}, { expand: true }) .file(some-file.txt) .contents() // contents contents in foo file在该测试中写入目录时使用了字面量路径/some-path/bar读取时则通过${foo}foobar动态指向同一目录从而验证了“写入路径与读取路径解耦”的能力。同时expand还可以配合写入侧使用。测试 core/integration/container_test.go 展示了对称的写入场景const output await client .container() .from(alpine:latest) .withEnvVariable(foo, bar) .withDirectory( /some-path/${foo}, // 写入时展开 client.directory().withNewFile(/some-file.txt, contents in foo file), { expand: true }, ) .directory(/some-path/bar, { expand: true }) // 读取时展开 .file(some-file.txt) .contents()使用限制secret 与 volatile 变量不可展开expandEnvVar在展开前会收集容器内的两类特殊变量并明确拒绝展开见 core/schema/container.go通过withSecretVariable注入的密钥环境变量通过withVolatileVariable注入的易变volatile环境变量。一旦path中引用了它们引擎会返回形如expand cannot be used with secret env variable GITEA_TOKEN或expand cannot be used with volatile env variable RUN_ID的错误。对应测试见 core/integration/container_test.gosecret与 core/integration/container_test.govolatile。这样设计是为了避免密钥值被意外写入路径 / 缓存键以及防止每次运行都可能变化的 volatile 值破坏构建缓存的可复现性。若变量未在容器环境中定义os.Expand会将其替换为空字符串这一点在使用时需要留意。与相关 API 的一致性expand并非directory独有它是 Dagger Container API 中路径型参数的通用能力同类选项包括ContainerWithDirectoryOpts.expandwithDirectory写入目录时展开路径ContainerFileOpts.expand/ContainerWithFileOpts.expandfile/withFile取回与写入文件时展开ContainerWithNewFileOpts.expand、ContainerWithoutDirectoryOpts.expand、ContainerWithMountedDirectoryOpts.expand等覆盖新建文件、删除目录、挂载目录等场景。在 core/integration/container_test.go 的TestEnvExpand中以上场景均有对应测试用例验证。这意味着你可以在构建流水线中统一采用“环境变量驱动路径”的约定先withEnvVariable定义构建产物路径如BUILD_DIR/out/release再在所有文件系统操作处配合{ expand: true }引用从而避免在多个调用点重复硬编码路径字符串。小结ContainerDirectoryOpts结构简单但语义明确通过expand布尔选项Container.directory()可以按容器内环境变量动态解析目录路径支持$VAR与${VAR}两种语法配合withEnvVariable可以显著提升 Dagger 流水线中路径参数的可维护性。使用时需牢记两点展开针对容器环境而非宿主机环境secret 与 volatile 变量被明确禁止用于展开。【免费下载链接】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），仅供参考