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/dagger

Dagger 的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.md：

export 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 }

它作为一个object类型别名存在，作为Container.directory方法的第二参数传入。在 SDK 客户端中，其典型使用形态如下（见 sdk/typescript/src/api/client.gen.ts）：

directory = (path: string, opts?: ContainerDirectoryOpts): Directory => { const ctx = this._ctx.select("directory", { path, ...opts }) return new Directory(ctx) }

该方法的 GraphQL 语义在核心 Schema 中定义（见 core/schema/container.go）：directory(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.go）：

type 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）的实现要点如下：

1. 若expand为false，直接原样返回输入路径；
2. 若为true，先读取容器的镜像配置（parent.ImageConfig），取得当前环境变量集合；
3. 调用 Go 标准库的os.Expand，对"${VAR}"/"$VAR"进行替换，变量值来自容器自身的cfg.Env；
4. 替换完成后，路径再经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}（foo=bar）动态指向同一目录，从而验证了“写入路径与读取路径解耦”的能力。

同时，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.go（secret）与 core/integration/container_test.go（volatile）。

这样设计是为了避免密钥值被意外写入路径 / 缓存键，以及防止每次运行都可能变化的 volatile 值破坏构建缓存的可复现性。若变量未在容器环境中定义，os.Expand会将其替换为空字符串，这一点在使用时需要留意。

与相关 API 的一致性

expand并非directory独有，它是 Dagger Container API 中路径型参数的通用能力，同类选项包括：

• ContainerWithDirectoryOpts.expand：withDirectory写入目录时展开路径；
• ContainerFileOpts.expand/ContainerWithFileOpts.expand：file/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