Dagger TypeScript SDK EnvFileVariablesOpts 详解:raw 选项与 .env 变量读取的底层语义
Dagger TypeScript SDK EnvFileVariablesOpts 详解:raw 选项与 .env 变量读取的底层语义
本文聚焦 Dagger v0.20 TypeScript SDK 生成的 API 类型别名 EnvFileVariablesOpts,它是 EnvFile.variables() 方法(读取 .env 文件中全部变量的查询入口)的可选参数类型。通过源码级分析,你将完整掌握 raw: boolean 选项控制"引号剥离与变量展开"的准确语义、底层 dotenv 解析引擎的实现机制,以及如何在 Dagger Pipeline 中按原始字面量或展开后的值读取环境变量。文章还覆盖了与之同源的 EnvFileGetOpts、namespace() 等周边 API,帮助你避免常见的解析陷阱。
一、类型定义:一个字段、一行注释背后的完整语义
该类型别名定义于版本化文档 EnvFileVariablesOpts.md,其完整定义极简:
type EnvFileVariablesOpts = {
/**
* Return values exactly as written to the file.
* No quote removal or variable expansion
*/
raw?: boolean
}
即:一个可选的 raw 布尔字段,控制返回值是否"完全按照文件中的原始写法返回,不进行引号移除,也不进行变量展开"。
在 TypeScript SDK 的生成代码中,这个类型位于 sdk/typescript/src/api/client.gen.ts,并被 EnvFile.variables 方法使用:
/**
* Return all variables
* @param opts.raw Return values exactly as written to the file. No quote removal or variable expansion
*/
variables = async (opts?: EnvFileVariablesOpts): Promise<EnvVariable[]> => {
type variables = { id: ID }
const ctx = this._ctx.select("variables", { ...opts }).select("id")
const response: Awaited<variables[]> = await ctx.execute()
return response.map(
(r) => new EnvVariable(ctx.copy().selectNode(r.id, "EnvVariable")),
)
}
从生成代码可以看到:opts 会被透传到 GraphQL 查询 select("variables", { ...opts }),最终映射为一个个 EnvVariable 对象(每个对象包含 name 与 value 字段)。如果你不传 raw(或传 false),读取到的值会经过引号剥离与变量展开;只有显式传 raw: true,才能拿到文件中逐字书写的内容。
同源的还有
EnvFileGetOpts(见 client.gen.ts),它同样只包含一个raw?: boolean字段,服务于EnvFile.get(name)单变量查询。两者共享同一份语义说明。
二、raw 语义的源码级拆解:引号剥离与变量展开到底做了什么
要真正理解 raw 选项,需要看引擎侧的实现。EnvFile.variables() 的解析入口是 core/envfile.go:
// Variables returns all variables
func (ef *EnvFile) Variables(ctx context.Context, raw bool) ([]EnvVariable, error) {
if raw {
return ef.variablesRaw(ctx)
}
return ef.variables(ctx, false)
}
func (ef *EnvFile) variablesRaw(_ context.Context) (vars EnvVariables, _ error) {
for name, value := range dotenv.AllRaw(ef.Environ) {
vars = append(vars, EnvVariable{Name: name, Value: value})
}
vars.Sort() // dotenv.AllRaw returns a map, so we must keep the ordering consistent for hashing purposes
return vars, nil
}
func (ef *EnvFile) variables(ctx context.Context, allowUnboundVariables bool) (vars EnvVariables, _ error) {
hostGetEnv := func(name string) string {
// Fallback to using host values for expansion
return Host{}.GetEnv(ctx, name)
}
all, err := dotenv.AllWithContext(ef.Environ, ef.Context, hostGetEnv, !allowUnboundVariables)
if err != nil {
return nil, err
}
for name, value := range all {
vars = append(vars, EnvVariable{Name: name, Value: value})
}
vars.Sort()
return vars, nil
}
两条路径的差异一目了然:
| 调用方式 | 底层函数 | 处理行为 |
|---|---|---|
raw: false(默认) |
dotenv.AllWithContext |
进行变量展开($VAR / ${VAR} 引用其他变量)、引号移除(单双引号与转义处理),并以 expand 依赖关系解析求值;未定义变量默认视为错误 |
raw: true |
dotenv.AllRaw |
不做任何加工,返回文件中逐字书写的内容 |
注意两个实现细节:
- 一致性排序:
dotenv.AllRaw与dotenv.All均返回 map,因此引擎会统一执行vars.Sort()以保证哈希与缓存的一致性——这正是 Dagger 缓存正确性的基础。 - 展开时的宿主回退:非 raw 路径会传入
hostGetEnv作为兜底,即文件中引用但未定义的变量,会回退到宿主环境变量继续展开(见 core/envfile.go)。
同理,单变量查询 EnvFile.get(name) 的 raw 参数在 core/envfile.go 中走 dotenv.LookupRaw 或 dotenv.LookupWithContext,语义完全一致。
三、底层 dotenv 解析引擎:从原始行到展开值的求值图
raw: false 的展开路径远比"字符串替换"复杂,其核心是一个带依赖解析与循环检测的求值图(GraphEvaluator),实现在 core/dotenv/dotenv.go:
// GraphEvaluator evaluates dotenv variables with dependency resolution and cycle detection
type GraphEvaluator struct {
raw map[string]*parsedEntry // Raw parsed entries (unexpanded)
expanded map[string]string // Memoized expanded values
expanding map[string]bool // Currently expanding (for cycle detection)
systemLookup func(string) string
NoUnset bool
}
// parsedEntry stores the parsed but unexpanded shell words
type parsedEntry struct {
name string
value *syntax.Word // The parsed shell word, not yet expanded
args []*syntax.Word // Additional args (for 'foo=a b c' case)
}
它的解析流程值得展开说明:
- 先解析、后展开:所有行首先被解析为未展开的 shell word(使用
mvdan.cc/sh的 shell 语法解析器),再按依赖关系求值,天然支持A=$B这类跨变量引用; - 循环检测:
expanding映射跟踪"正在展开中"的变量,发现A=$B; B=$A这类循环引用时直接报错,避免死循环; export前缀兼容:parseEntry会先StripExportPrefix,因此export KEY=value与KEY=value等价,兼容 direnv、set -a; . ./.env、shellsource等主流 .env 加载约定(见 core/dotenv/dotenv.go);- 快慢双路径:对于
simpleKeyRegexp匹配且不含 shell 特性的简单赋值走快速路径;含引号、展开、反引号等复杂内容才走完整 shell 解析器,兼顾性能与语义正确性。
这解释了文档注释中"quote removal or variable expansion"的完整含义:默认路径下,"hello world" 的引号会被剥离为 hello world,"$ANIMAL" 会被展开为其他变量的值;而 raw: true 则原样返回 "hello world" 与 "$ANIMAL" 的字面文本。
四、实战用法:在 TypeScript SDK 中读取 .env 变量
EnvFileVariablesOpts 的典型消费方式是配合 client.envFile()(GraphQL 入口见 core/schema/envfile.go)或 File.asEnvFile() 使用。生成 SDK 中 EnvFile.variables 的调用形态如下:
import { client, file } from "@dagger.io/dagger"
// 方式一:直接构造空的 EnvFile 再写入变量
const ef = client.envFile()
.withVariable("MY_APP_TOKEN", "topsecret")
.withVariable("MY_APP_NAME", "hello")
// 默认读取:经过引号剥离与变量展开
const vars = await ef.variables()
// 逐字读取:完全按文件书写返回
const rawVars = await ef.variables({ raw: true })
对于来自容器/宿主目录的 .env 文件,则先通过 asEnvFile() 解析再查询:
const env = client
.host()
.directory(".")
.file(".env")
.asEnvFile()
const rawVars = await env.variables({ raw: true })
对应的 CLI 形态(集成测试中可见,见 core/integration/envfile_test.go):
dagger core host file --path=.env as-env-file variables value
这里 variables 是查询名,value 是取值的子字段——CLI 同样遵循"默认展开、可指定 raw"的同一套 GraphQL 语义。
五、raw 的真实效果:集成测试中的对照样本
core/integration/envfile_test.go 用大量用例锁定了 raw 与非 raw 的行为差异,这是理解 EnvFileVariablesOpts 最直观的证据。例如:
# 文件内容
QUOTES="this sentence is double-quoted (with \"), 'and this is single-quoted'"
single_quoted_var="hello, nice '$animal'"
- 默认(展开):
QUOTES会被剥离外层双引号并处理转义;single_quoted_var中的$animal会被展开; - raw:
quotes返回"hello world"(含引号原文)、single_quotes返回'hello world'、dollar_sign返回含$的原文、连反引号命令替换与反斜杠转义都保持原样。
测试还专门覆盖了 JSON 场景(见 envfile_test.go):
no_quotes: ["ga", "bu", "zo", "meu", 42]
single_quotes: '["ga", "bu", "zo", "meu", 42]'
double_quotes: "[\"ga\", \"bu\", \"zo\", \"meu\", 42]"
结论是:JSON 数组/对象必须用引号包裹才能被正确解析——如果裸写 ["ga", ...],shell 词法会把 [ 与 "ga", 当成多个 token,从而破坏变量值。这正是"引号剥离"语义在生产环境中最常见的坑:需要保留结构化字面量时,优先考虑 raw: true。
六、周边 API 家族:与 EnvFileVariablesOpts 协同的类型与函数
EnvFileVariablesOpts 并非孤立存在,它隶属于完整的 EnvFile API 家族(GraphQL 定义见 core/schema/envfile.go),相关能力包括:
| 能力 | 说明 | 相关类型/参数 |
|---|---|---|
variables(opts) |
返回全部变量 | EnvFileVariablesOpts(raw) |
get(name, opts) |
单变量查询,同名后者生效,未找到返回空串 | EnvFileGetOpts(raw) |
namespace(prefix) |
按前缀过滤并剥离前缀,支持 camelCase/snake_case 与大小写不敏感的灵活前缀匹配 | prefix: string |
withVariable / withoutVariable |
增删变量 | name、value |
exists(name) |
检查变量是否存在 | name |
asFile() |
将 EnvFile 重新导出为文件 | — |
其中 namespace 的实现值得注意(见 core/envfile.go):它内部刻意使用 raw 变量做前缀过滤(因为值会在后续使用时才展开),并且把不匹配前缀的变量作为"隐藏展开上下文"保留,使得 SOURCE=${ROOT_DIR} 这类跨命名空间引用在后续展开时依然有效。前缀匹配通过 cutFlexPrefix 同时尝试 myApp_ 与 my_app_ 两种风格,且大小写不敏感。
七、最佳实践小结
- 需要环境变量的"字面值"(如含引号、
$、反引号的字符串,或 JSON 结构)时,务必传raw: true,否则引擎会按 shell 语义剥离引号并展开变量; - 默认路径适合"求值后"的值:文件内引用其他变量(如
API_URL=${BASE_URL}/v1)时,不传raw即可拿到完整展开结果; - 依赖宿主变量是可预期的行为:展开时未定义的变量会回退到宿主环境(见 core/envfile.go),跨环境运行时要注意宿主差异;
- 循环引用会报错:求值图内置循环检测,
A=$B; B=$A这类文件会在读取时直接失败,而不是死循环; - 所有 API 都以
EnvVariable{name, value}形式返回,且引擎会统一排序保证缓存一致性,因此读取顺序不应被当作业务依赖。
无论是逐字搬运配置文件,还是做展开后的环境注入,EnvFileVariablesOpts.raw 都是控制 Dagger EnvFile 语义的唯一开关。理解它背后的求值图与解析约定,就能安全地在 CI 与云环境中复现与宿主机一致的 .env 行为。