尧图网站建设 
Dagger TypeScript SDKDirectory.withFile 与 DirectoryWithFileOpts 详解【免费下载链接】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 参考文档中的DirectoryWithFileOpts类型别名为核心讲解如何在声明式 Pipeline 中通过Directory.withFile()将单个文件以精确的属主owner与权限permissions复制进目录快照。读完本文你将掌握owner、permissions两个可选参数的含义、默认行为与底层实现原理并能在模块代码中组合使用withFile/withFiles/withNewFile等目录操作完成文件注入与打包场景。一、类型别名概览DirectoryWithFileOpts 是什么在 Dagger TypeScript SDK 的客户端生成代码中DirectoryWithFileOpts被定义为object类型的 TypeScript 类型别名type alias用于描述Directory.withFile()方法在复制文件进入目录时可选携带的配置项。其定义位于 sdk/typescript/src/api/client.gen.tsexport type DirectoryWithFileOpts { /** * Permission given to the copied file (e.g., 0600). */ permissions?: number /** * A user:group to set for the copied 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 }该类型与DirectoryWithFilesOpts批量复制、仅含permissions、DirectoryWithDirectoryOpts、DirectoryWithNewFileOpts、DirectoryWithNewDirectoryOpts等一起构成 Dagger 目录对象with*系列操作的可选参数族。你可以在同一文件 client.gen.ts 中看到其姊妹类型。说明该类型由 Dagger Codegen 从 GraphQL 核心 APIcore/directory.go中的withFile字段定义自动生成因此sdk/typescript/src/api/client.gen.ts属于“生成文件”普通用户不应直接编辑但阅读它有助于理解 SDK 的最终形态。二、参数详解owner 与 permissionsDirectoryWithFileOpts只包含两个可选的属性下面逐一说明其语义、格式与默认行为。2.1 owner可选复制后文件的属主类型string含义设置被复制文件以及承载它的目录的用户与组user:group。取值格式数字 ID 形式如1000:1000名称形式如foo:bar。默认行为如果只给出用户而省略组组默认与用户相同。例如owner: 1000等价于1000:1000owner: foo等价于foo:foo。在底层实现中owner会被解析为 Dagger 内部的Ownership结构。参见 core/directory.go当owner ! 时核心引擎会调用resolveDirectoryOwner(root, owner)将其解析为属主信息最终通过layercopy.CopyOptions.Chown在文件复制CopyFile时应用 chown 语义。若解析失败会返回形如failed to parse ownership %s的错误。2.2 permissions可选复制后文件的权限位类型number含义赋予被复制文件的权限permission bits以八进制数值形式给出。取值示例0600属主读写、0644属主读写、组与其他只读、0755可执行文件/脚本的常见权限。注意官方文档与生成代码中的示例是0600而在底层 GraphQL 定义与DirectoryWithDirectoryOpts中权限示例为0755说明该字段按八进制文件模式语义工作number类型直接用数字字面量书写即可JavaScript 中0600会被解析为八进制字面量 384等价于十进制 384含义不变。实现上permissions会被映射为layercopy.CopyOptions.Mode见 core/directory.go在复制文件时通过 layercopy 设置目标文件模式。若不传该参数则保留源文件自身的权限位。三、核心用法Directory.withFile 与相关方法DirectoryWithFileOpts单独使用没有意义它总是作为Directory.withFile()的可选第三参数出现。SDK 中该方法的完整签名见 client.gen.ts/** * Retrieves this directory plus the contents of the given file copied to the given path. * param path Location of the copied file (e.g., /file.txt). * param source Identifier of the file to copy. * param opts.permissions Permission given to the copied file (e.g., 0600). * param opts.owner A user:group to set for the copied directory and its contents. */ withFile ( path: string, source: File, opts?: DirectoryWithFileOpts, ): Directory { const ctx this._ctx.select(withFile, { path, source, ...opts }) return new Directory(ctx) }关键点path目标位置例如/file.txtsource要复制的File对象通常来自host().file(...)、directory().file(...)或容器导出opts即DirectoryWithFileOpts两个字段均可选惰性求值该方法只是通过this._ctx.select(withFile, {...})构造一条 GraphQL 选择selection真正执行发生在结果被消费如export、entries、container引用时因此可以安全地链式组合而不会立即触发 I/O。withFile在 SDK 中并非Directory独有Container也提供同名方法client.gen.ts其 opts 类型为ContainerWithFileOpts还额外支持inheritOwner、expand。本类型别名仅用于Directory场景。3.1 实战示例向目录快照注入配置并指定属主与权限import { dag, Directory, File } from dagger.io/dagger // 1. 从宿主机读取一个配置文件例如私有密钥 const secretFile: File dag.host().file(/home/user/.ssh/id_ed25519) // 2. 将文件复制进目录并设置 0600 权限与 1000:1000 属主 const target: Directory dag .directory() .withFile(/app/.ssh/id_ed25519, secretFile, { permissions: 0600, owner: 1000:1000, }) // 3. 挂载进容器后运行 const result await dag .container() .from(alpine:latest) .withDirectory(/, target) .withExec([sh, -c, stat -c %a %u %g /app/.ssh/id_ed25519]) .stdout() console.log(result) // 期望输出类似 600 1000 1000注意事项0600在 TypeScript 中以八进制字面量书写编译为 ES 目标时可能要求esModuleInterop/较新的语法支持也可以写成十进制384或0o600以确保兼容性若省略owner复制后的文件属主将是 Dagger 引擎执行上下文中的默认属主而不是宿主机原文件的属主permissions与owner相互独立可单独使用其一。四、结合相关方法withFiles 与 withNewFile围绕文件注入SDK 还提供两个相邻方法便于对照选择方法签名语义opts 类型withFile(path, source: File, opts?)复制单个文件到指定路径DirectoryWithFileOptswithFiles(path, sources: File[], opts?)将多个文件批量复制到指定目录DirectoryWithFilesOpts仅permissionswithNewFile(path, contents: string, opts?)直接以字符串内容新建文件DirectoryWithNewFileOptswithFiles的目标path是目录位置如/src且其 opts 目前只暴露permissions不支持逐文件ownerwithNewFile适合无需File对象、直接写入文本的场景例如生成.npmrc、entrypoint.sh同样支持permissions。三者的 SDK 定义均可在 client.gen.ts 中找到语义与withFile完全一致的Container.withFile/withFiles定义见同文件 L6016-L6045。五、源码级原理withFile 在核心引擎中如何执行DirectoryWithFileOpts的两个字段最终进入 Dagger 核心引擎的(*Directory).WithFile实现core/directory.gofunc (dir *Directory) WithFile( ctx context.Context, parent dagql.ObjectResult[*Directory], destPath string, src dagql.ObjectResult[*File], permissions *int, owner string, doNotCreateDestPath bool, attemptUnpackDockerCompatibility bool, ) error执行流程可概括为以下几步缓存求值通过dagql.EngineCache(ctx)先对父目录parent与源文件src求值获取两者的快照snapshot引用core/directory.go目标路径归一化判断destPath是否以/或/.结尾以区分“目标是一个目录”的语义再与当前目录拼接得到最终路径core/directory.go创建新的快照层基于父目录快照生成一个新的可变快照withfile dest src作为 UsageRecord 描述整个复制在挂载的根文件系统内完成core/directory.go解析属主与权限owner非空时解析为Ownership与permissions一起组装为layercopy.CopyOptions{ Chown, Mode, ReplaceExisting: true, ... }core/directory.go执行复制以只读方式挂载源快照调用copier.CopyFile(...)将文件复制到目标路径应用 chown 与权限模式core/directory.go。这段实现印证了文档中的两个关键事实owner支持数字 ID 与名称两种形式因为引擎内部统一通过resolveDirectoryOwner解析后再交给文件系统层permissions是八进制模式位直接映射到复制操作的模式参数未指定时保留源文件权限。六、与其他 SDK 及文档资源的对应关系TypeScript SDK 生成源类型别名与withFile方法均由 Codegen 从核心 GraphQL Schema 生成完整源码见 sdk/typescript/src/api/client.gen.tsTypeScript 运行时SDK 运行时同样维护了一份 Go 生成代码sdk/typescript/runtime/internal/dagger/dagger.gen.go其中也包含DirectoryWithFileOpts相关定义SDK 测试用例sdk/typescript/src/api/test/api.spec.ts中对withFile/withFiles有实际调用可作为集成用法参考Dagger 0.21 TypeScript SDK 参考首页本类型所在参考文档的完整索引入口见 docs/versioned_docs/version-0.21/reference/typescript/api/client.gen/type-aliases 所在目录的上级页面核心引擎实现跨语言 SDK 共享的底层语义由 core/directory.go 的WithFile方法承载。七、常见问题与使用建议Q1owner不传时文件的属主是谁复制操作沿用引擎默认属主不会自动保留源文件的属主信息。需要精确控制运行用户时例如设置容器内非 root 用户可读的 SSH 密钥务必显式传入owner。Q2permissions不传时权限如何决定保留源文件File对象所代表的快照的既有权限位。需要固定产物权限时如生成可执行脚本0755、敏感配置0600建议显式指定。Q3withFile与withFiles如何选择单文件用withFile可同时设置 owner 与 permissions批量注入且无需改属主时用withFiles纯文本内容用withNewFile更简洁。Q4是否支持把DirectoryWithFileOpts直接传给Container.withFile不支持。Container.withFile使用的是ContainerWithFileOpts额外包含inheritOwner、expand两个字段两者类型不同不能混用。最佳实践小结在构建产物/镜像时用withFile(path, file, { permissions: 0644 })固定文件模式避免宿主机与 CI 环境权限不一致导致的可复现性问题涉及密钥、证书等敏感文件时使用permissions: 0o600与明确的owner防止文件在容器内被其他用户读取将多个withFile链式调用后再统一export或挂载进容器利用 Dagger 的惰性求值避免中间态落盘。【免费下载链接】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：Directory.withFile 与 DirectoryWithFileOpts 详解
Dagger TypeScript SDKDirectory.withFile 与 DirectoryWithFileOpts 详解【免费下载链接】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 参考文档中的DirectoryWithFileOpts类型别名为核心讲解如何在声明式 Pipeline 中通过Directory.withFile()将单个文件以精确的属主owner与权限permissions复制进目录快照。读完本文你将掌握owner、permissions两个可选参数的含义、默认行为与底层实现原理并能在模块代码中组合使用withFile/withFiles/withNewFile等目录操作完成文件注入与打包场景。一、类型别名概览DirectoryWithFileOpts 是什么在 Dagger TypeScript SDK 的客户端生成代码中DirectoryWithFileOpts被定义为object类型的 TypeScript 类型别名type alias用于描述Directory.withFile()方法在复制文件进入目录时可选携带的配置项。其定义位于 sdk/typescript/src/api/client.gen.tsexport type DirectoryWithFileOpts { /** * Permission given to the copied file (e.g., 0600). */ permissions?: number /** * A user:group to set for the copied 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 }该类型与DirectoryWithFilesOpts批量复制、仅含permissions、DirectoryWithDirectoryOpts、DirectoryWithNewFileOpts、DirectoryWithNewDirectoryOpts等一起构成 Dagger 目录对象with*系列操作的可选参数族。你可以在同一文件 client.gen.ts 中看到其姊妹类型。说明该类型由 Dagger Codegen 从 GraphQL 核心 APIcore/directory.go中的withFile字段定义自动生成因此sdk/typescript/src/api/client.gen.ts属于“生成文件”普通用户不应直接编辑但阅读它有助于理解 SDK 的最终形态。二、参数详解owner 与 permissionsDirectoryWithFileOpts只包含两个可选的属性下面逐一说明其语义、格式与默认行为。2.1 owner可选复制后文件的属主类型string含义设置被复制文件以及承载它的目录的用户与组user:group。取值格式数字 ID 形式如1000:1000名称形式如foo:bar。默认行为如果只给出用户而省略组组默认与用户相同。例如owner: 1000等价于1000:1000owner: foo等价于foo:foo。在底层实现中owner会被解析为 Dagger 内部的Ownership结构。参见 core/directory.go当owner ! 时核心引擎会调用resolveDirectoryOwner(root, owner)将其解析为属主信息最终通过layercopy.CopyOptions.Chown在文件复制CopyFile时应用 chown 语义。若解析失败会返回形如failed to parse ownership %s的错误。2.2 permissions可选复制后文件的权限位类型number含义赋予被复制文件的权限permission bits以八进制数值形式给出。取值示例0600属主读写、0644属主读写、组与其他只读、0755可执行文件/脚本的常见权限。注意官方文档与生成代码中的示例是0600而在底层 GraphQL 定义与DirectoryWithDirectoryOpts中权限示例为0755说明该字段按八进制文件模式语义工作number类型直接用数字字面量书写即可JavaScript 中0600会被解析为八进制字面量 384等价于十进制 384含义不变。实现上permissions会被映射为layercopy.CopyOptions.Mode见 core/directory.go在复制文件时通过 layercopy 设置目标文件模式。若不传该参数则保留源文件自身的权限位。三、核心用法Directory.withFile 与相关方法DirectoryWithFileOpts单独使用没有意义它总是作为Directory.withFile()的可选第三参数出现。SDK 中该方法的完整签名见 client.gen.ts/** * Retrieves this directory plus the contents of the given file copied to the given path. * param path Location of the copied file (e.g., /file.txt). * param source Identifier of the file to copy. * param opts.permissions Permission given to the copied file (e.g., 0600). * param opts.owner A user:group to set for the copied directory and its contents. */ withFile ( path: string, source: File, opts?: DirectoryWithFileOpts, ): Directory { const ctx this._ctx.select(withFile, { path, source, ...opts }) return new Directory(ctx) }关键点path目标位置例如/file.txtsource要复制的File对象通常来自host().file(...)、directory().file(...)或容器导出opts即DirectoryWithFileOpts两个字段均可选惰性求值该方法只是通过this._ctx.select(withFile, {...})构造一条 GraphQL 选择selection真正执行发生在结果被消费如export、entries、container引用时因此可以安全地链式组合而不会立即触发 I/O。withFile在 SDK 中并非Directory独有Container也提供同名方法client.gen.ts其 opts 类型为ContainerWithFileOpts还额外支持inheritOwner、expand。本类型别名仅用于Directory场景。3.1 实战示例向目录快照注入配置并指定属主与权限import { dag, Directory, File } from dagger.io/dagger // 1. 从宿主机读取一个配置文件例如私有密钥 const secretFile: File dag.host().file(/home/user/.ssh/id_ed25519) // 2. 将文件复制进目录并设置 0600 权限与 1000:1000 属主 const target: Directory dag .directory() .withFile(/app/.ssh/id_ed25519, secretFile, { permissions: 0600, owner: 1000:1000, }) // 3. 挂载进容器后运行 const result await dag .container() .from(alpine:latest) .withDirectory(/, target) .withExec([sh, -c, stat -c %a %u %g /app/.ssh/id_ed25519]) .stdout() console.log(result) // 期望输出类似 600 1000 1000注意事项0600在 TypeScript 中以八进制字面量书写编译为 ES 目标时可能要求esModuleInterop/较新的语法支持也可以写成十进制384或0o600以确保兼容性若省略owner复制后的文件属主将是 Dagger 引擎执行上下文中的默认属主而不是宿主机原文件的属主permissions与owner相互独立可单独使用其一。四、结合相关方法withFiles 与 withNewFile围绕文件注入SDK 还提供两个相邻方法便于对照选择方法签名语义opts 类型withFile(path, source: File, opts?)复制单个文件到指定路径DirectoryWithFileOptswithFiles(path, sources: File[], opts?)将多个文件批量复制到指定目录DirectoryWithFilesOpts仅permissionswithNewFile(path, contents: string, opts?)直接以字符串内容新建文件DirectoryWithNewFileOptswithFiles的目标path是目录位置如/src且其 opts 目前只暴露permissions不支持逐文件ownerwithNewFile适合无需File对象、直接写入文本的场景例如生成.npmrc、entrypoint.sh同样支持permissions。三者的 SDK 定义均可在 client.gen.ts 中找到语义与withFile完全一致的Container.withFile/withFiles定义见同文件 L6016-L6045。五、源码级原理withFile 在核心引擎中如何执行DirectoryWithFileOpts的两个字段最终进入 Dagger 核心引擎的(*Directory).WithFile实现core/directory.gofunc (dir *Directory) WithFile( ctx context.Context, parent dagql.ObjectResult[*Directory], destPath string, src dagql.ObjectResult[*File], permissions *int, owner string, doNotCreateDestPath bool, attemptUnpackDockerCompatibility bool, ) error执行流程可概括为以下几步缓存求值通过dagql.EngineCache(ctx)先对父目录parent与源文件src求值获取两者的快照snapshot引用core/directory.go目标路径归一化判断destPath是否以/或/.结尾以区分“目标是一个目录”的语义再与当前目录拼接得到最终路径core/directory.go创建新的快照层基于父目录快照生成一个新的可变快照withfile dest src作为 UsageRecord 描述整个复制在挂载的根文件系统内完成core/directory.go解析属主与权限owner非空时解析为Ownership与permissions一起组装为layercopy.CopyOptions{ Chown, Mode, ReplaceExisting: true, ... }core/directory.go执行复制以只读方式挂载源快照调用copier.CopyFile(...)将文件复制到目标路径应用 chown 与权限模式core/directory.go。这段实现印证了文档中的两个关键事实owner支持数字 ID 与名称两种形式因为引擎内部统一通过resolveDirectoryOwner解析后再交给文件系统层permissions是八进制模式位直接映射到复制操作的模式参数未指定时保留源文件权限。六、与其他 SDK 及文档资源的对应关系TypeScript SDK 生成源类型别名与withFile方法均由 Codegen 从核心 GraphQL Schema 生成完整源码见 sdk/typescript/src/api/client.gen.tsTypeScript 运行时SDK 运行时同样维护了一份 Go 生成代码sdk/typescript/runtime/internal/dagger/dagger.gen.go其中也包含DirectoryWithFileOpts相关定义SDK 测试用例sdk/typescript/src/api/test/api.spec.ts中对withFile/withFiles有实际调用可作为集成用法参考Dagger 0.21 TypeScript SDK 参考首页本类型所在参考文档的完整索引入口见 docs/versioned_docs/version-0.21/reference/typescript/api/client.gen/type-aliases 所在目录的上级页面核心引擎实现跨语言 SDK 共享的底层语义由 core/directory.go 的WithFile方法承载。七、常见问题与使用建议Q1owner不传时文件的属主是谁复制操作沿用引擎默认属主不会自动保留源文件的属主信息。需要精确控制运行用户时例如设置容器内非 root 用户可读的 SSH 密钥务必显式传入owner。Q2permissions不传时权限如何决定保留源文件File对象所代表的快照的既有权限位。需要固定产物权限时如生成可执行脚本0755、敏感配置0600建议显式指定。Q3withFile与withFiles如何选择单文件用withFile可同时设置 owner 与 permissions批量注入且无需改属主时用withFiles纯文本内容用withNewFile更简洁。Q4是否支持把DirectoryWithFileOpts直接传给Container.withFile不支持。Container.withFile使用的是ContainerWithFileOpts额外包含inheritOwner、expand两个字段两者类型不同不能混用。最佳实践小结在构建产物/镜像时用withFile(path, file, { permissions: 0644 })固定文件模式避免宿主机与 CI 环境权限不一致导致的可复现性问题涉及密钥、证书等敏感文件时使用permissions: 0o600与明确的owner防止文件在容器内被其他用户读取将多个withFile链式调用后再统一export或挂载进容器利用 Dagger 的惰性求值避免中间态落盘。【免费下载链接】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），仅供参考