纹理采样是WebGPU渲染管线里的基础环节。当片段着色器通过textureSample函数读取纹理时，传入的UV坐标经常落在0到1之外。GPU此时的行为由采样器描述中的地址模式决定，它告诉硬件如何访问纹理边界以外的区域。TypeScript项目里如果把这些模式直接写成字符串，开发阶段就很难发现拼写错误，因此需要显式定义相关数据类型。
AddressMode在WebGPU规范中的角色
WebGPU将纹理坐标视为归一化数值，0到1对应纹理的第一行到最后一列。当坐标小于0或大于1时，采样器必须按照某种规则映射回有效范围。规范里用AddressMode枚举描述这种规则，它有三个可选字符串值：repeat、mirror-repeat和clamp-to-edge。每个值都对应一套明确的数学处理方式，让纹理在超界坐标下仍能返回确定颜色。
repeat模式会对坐标取小数部分，相当于把纹理无限平铺；mirror-repeat则先对坐标取绝对值再取小数，形成镜像平铺效果；clamp-to-edge直接把坐标截断在0和1之间，超出部分取最近边缘的颜色。三者在视觉上差别明显，尤其是在大平铺表面或UI纹理中，选错模式会产生可见的接缝或边缘拉伸。
在WGSL着色器中，地址模式并不直接出现在代码里，而是绑定在采样器对象上。JavaScript或TypeScript负责创建采样器时填写描述字段，因此类型定义必须与规范中的字符串值保持一致。这个细节很关键，因为一旦某个模式的字符串拼错，运行时错误往往只出现在特定字体的GPU驱动日志里，排查成本较高。
TypeScript中定义AddressMode的两种方式
最轻量的做法是定义一个字符串字面量联合类型。这样既保留了规范里的原始值，又能让编译器在赋值时检查拼写。具体写法如下：
type AddressMode = "repeat" | "mirror-repeat" | "clamp-to-edge";
这种联合类型非常适合直接用在函数参数或对象字段上。例如有一个创建采样器的函数，它的参数类型可以直接声明为AddressMode，调用时如果写入"mirror_repeat"，TypeScript会立刻报错。联合类型不会生成任何运行时代码，对打包体积没有影响，适合偏爱轻量风格的项目。
另一种方式是使用枚举。枚举可以给每个字符串值起一个有语义的名字，并且在使用时获得编辑器自动补全。WebGPU的AddressMode值本身是字符串，所以用字符串枚举来对应：
enum AddressMode {
Repeat = "repeat",
MirrorRepeat = "mirror-repeat",
ClampToEdge = "clamp-to-edge",
}枚举相比联合类型多了一层命名抽象，代码中写AddressMode.MirrorRepeat比直接写"mirror-repeat"更容易阅读，也避免了记忆连字符位置。但枚举会被编译成对象，增加少量运行时开销。对于WebGPU这类频繁创建采样器的场景，这个开销通常可以忽略不计，更重要的是团队协作时命名一致。
两种方式并不冲突，项目中可以先用联合类型定义底层类型，再在需要命名语义的地方使用常量对象来模拟枚举。例如：
const AddressMode = {
Repeat: "repeat",
MirrorRepeat: "mirror-repeat",
ClampToEdge: "clamp-to-edge",
} as const;
type AddressMode = typeof AddressMode[keyof typeof AddressMode];这种写法兼顾了联合类型的轻量和命名访问的便利，很多现代TypeScript项目采用了类似模式。不过对于大部分WebGPU开发来说，直接使用type AddressMode = "repeat" | "mirror-repeat" | "clamp-to-edge";已经足够清晰。
在GPUSamplerDescriptor中使用类型
WebGPU创建采样器时需要传入GPUSamplerDescriptor对象，其中addressModeU、addressModeV、addressModeW三个字段分别控制纹理坐标的U、V、W方向。这三个字段的类型在官方类型定义库中通常已经声明为联合类型，但很多项目初期并没有引入@webgpu/types，而是手写接口，这时就会出现字符串散落各处的情况。
更安全的做法是定义一个接受AddressMode参数的辅助函数，把采样器创建逻辑集中起来：
function createTextureSampler(
device: GPUDevice,
modeU: AddressMode,
modeV: AddressMode,
modeW: AddressMode
) {
return device.createSampler({
addressModeU: modeU,
addressModeV: modeV,
addressModeW: modeW,
magFilter: "linear",
minFilter: "linear",
mipmapFilter: "linear",
});
}调用时传入AddressMode.Repeat或直接传字符串字面量，都能获得类型检查。如果某个成员不小心写了addressModeU: "mrrror-repeat"，编译器会标红。这比等到运行时在控制台里翻找WebGPU验证错误要高效得多。
对于需要依赖外部纹理资源的场景，例如加载用户上传的图片后创建采样器，可以把AddressMode类型用于材质配置接口：
interface MaterialSamplerConfig {
wrapU: AddressMode;
wrapV: AddressMode;
wrapW: AddressMode;
magFilter: "nearest" | "linear";
minFilter: "nearest" | "linear";
}这样材质数据在序列化或从服务端下发时，依然能保持类型约束。相比直接使用string类型，联合类型把可接受的范围缩小到了三个值，降低了无效数据进入渲染管线的概率。
三种模式的采样行为与视觉效果
repeat模式对纹理坐标使用fract()等效计算，1.2会被映射到0.2，-0.3会映射到0.7。这种模式适合草地、砖墙、地板等需要平铺重复的纹理，但缺点是当纹理本身左右不对称时，平铺边界会出现明显跳变。例如一张带有方向性花纹的贴图，repeat模式下每块纹理都保持同样朝向，视觉上比较机械。
mirror-repeat在计算时会先对坐标取绝对值再做小数运算，1.2先变成1.2，取小数得0.2，但位于奇数倍周期时还会进行1减小数运算，因此实际映射为0.8。这种操作让相邻平铺块呈镜像翻转，纹理边界处的像素连续性更好。对于法线贴图、粗糙度贴图这类要求平铺后没有方向突变的资源，mirror-repeat往往比repeat更合适。
clamp-to-edge则完全不进行周期计算，任何小于0的坐标都被当作0，大于1的坐标被当作1。这样超界区域会重复边缘像素，形成拉伸效果。它适合UI图标、文字纹理、后期处理输入等不希望出现平铺重复的场景。例如把一个按钮的纹理放大，使用clamp-to-edge可以避免按钮边缘出现重复花纹。
可以用一个具体坐标来感受三者的差异：假设UV坐标为1.2，repeat取0.2处纹素，mirror-repeat取0.8处纹素，clamp-to-edge取1.0处纹素。如果UV坐标为-0.7，repeat取0.3，mirror-repeat取0.7，clamp-to-edge取0.0。这些规则在编写自定义采样计算时必须牢记，否则着色器里手动实现平铺逻辑时容易与采样器行为不一致。
工程中的类型扩展与最佳实践
如果你的项目已经引入了@webgpu/types类型定义库，那么GPUAddressMode已经是现成的联合类型。此时不必重复定义自己的AddressMode，直接使用该类型可以保持与后续WebGPU规范更新一致。例如：
import type { GPUAddressMode } from "@webgpu/types";
function createSamplerWithMode(mode: GPUAddressMode) {
return device.createSampler({
addressModeU: mode,
addressModeV: mode,
addressModeW: mode,
});
}如果某个WebGPU版本新增了地址模式，类型定义库也会同步更新，你的封装函数只需修改联合类型即可。自己手写类型时也要注意查阅最新规范，避免将过时的模式值硬编码进项目。
在多人协作的渲染项目中，建议把WebGPU相关的类型定义集中到一个模块里，例如gpu-types.ts。采样器描述、着色器绑组布局、纹理格式等类型都可以统一维护。这样当需要调整纹理采样行为时，不用在多个组件文件里搜索字符串。
类型安全并不是银弹，但它能把WebGPU API中容易出错的字符串约束在编译期。对于AddressMode这种只有三个合法值的字段来说，联合类型或枚举是最简单有效的防线。选型时优先考虑团队已有的代码风格：偏好函数式且不引入运行时对象就选联合类型，偏好命名空间和自动补全就选枚举。无论哪种方式，都比裸字符串更可靠。
TypeScriptWebGPU纹理采样地址模式修改时间：2026-09-22 00:43:48