shaders

Shaders

Shaders 是一个 WebGPU 组件库。它只有一个包 shaders，其中的组件可以像 Figma 中的图层一样组合。以下所有内容均免费，并采用 MIT 许可证。适用时会标明 Pro。

设置项目

编写任何着色器代码之前，先在用户的项目中运行 CLI：

npx shaders connect

它会检测框架，使用项目的包管理器安装 shaders，写入 shaders.config.ts，通过浏览器登录用户，将代码库连接到 Shaders 项目（设计编辑器中的画布），并安装此技能。务必使用这样的显式子命令：单独运行 npx shaders 会打开面向用户的交互式菜单。在 CI 环境中或无法使用浏览器时，设置 SHADERS_API_KEY 为个人 API 密钥。--no-auth 会跳过登录，--yes 会跳过所有提示。

连接后，以下三个命令即可覆盖整个工作流：

npx shaders install              # pick shaders from the connected project; writes component files
npx shaders search "<look>"      # search the preset library by describing the look (free, no sign-in)
npx shaders preview offsets-1    # open a preset on shaders.com so the user can see it running
npx shaders install offsets-1    # a preset from the library, by name (Pro)
npx shaders update               # pull in what the user changed in the design editor
npx shaders open                 # open the connected project in the design editor

每次安装都会在 outDir 中写入一个组件文件（记录在 shaders.lock.json 中），其中包含完整的组件树，且所有 prop 都内联其中。将其视为普通源代码：编辑 prop，将其绑定到状态，并与其他效果组合。除非传入 --force，否则 update 不会改动含有本地编辑的文件。

用户请求某种效果时：

1. 如果一两个组件就能实现（带光标轨迹的渐变、模糊图像、覆盖在 logo 上的玻璃效果、文字背后的噪点），就从以下组件中手动组合实现。优先尝试这种方式。
2. 否则搜索预设库： npx shaders search "liquid chrome hero background" --json。结果包含名称、描述、匹配分数和页面 URL。让用户通过 npx shaders preview <name> 查看候选效果的运行情况（会打开 shaders.com），然后用 npx shaders install <name> 安装（Pro，见下文）。
3. 如果用户已在编辑器中设计好效果： 运行 npx shaders install 并选择该效果。

MCP 服务（npx shaders install-mcp）提供搜索预设、读取着色器 prop 以及从 SVG 生成 SDF 文件的工具。安装后即可使用。

组合效果

<Shader> 会渲染一个 <canvas>。其中的组件是图层，按顺序绘制：第一个子项位于底部，最后一个位于最上方。

import { Shader, LinearGradient, CursorTrail } from 'shaders/react'

<Shader className="w-full h-64">
  <LinearGradient colorA="#0f172a" colorB="#7c3aed" angle={45} colorSpace="oklch" />
  <CursorTrail />
</Shader>

适用于所有组件的规则：

• 使用 <Shader> 上的 CSS 设置画布尺寸（class、className 或 style）。画布本身没有尺寸，会随容器调整大小。切勿为内部的 <canvas> 设置样式。
• 效果会应用于它们之前绘制的内容。 转换图像的组件（模糊、扭曲、调整、风格化、形状效果、过渡）都是效果。将其作为同级组件放置时，它会应用于树中位于其上方的所有图层，因此默认采用平铺堆叠：图像，然后是 Blur，再然后是 Vignette。只有在效果必须仅作用于特定图层、而不影响其他内容时，才将图层嵌套在效果中（例如，只让某个网格产生波纹，而其后的漩涡保持静止）。components.md 中会将效果标记为“需要输入”；它们需要前面已绘制的内容或嵌套在其中的内容。生成器（纹理、形状）可以独立绘制。
• 所有组件都有的通用属性： blendMode（normal、multiply、screen、overlay、softLight、hardLight、linearDodge、linearBurn、colorDodge、colorBurn、darken、lighten、difference、exclusion、hue、saturation、color、luminosity）、opacity（0–1）、visible、maskSource + maskType、boundingBox、absolute。
• 蒙版： 为蒙版图层设置 id，将其 visible={false}，并在要添加蒙版的图层上设置 maskSource="thatId"。隐藏的图层仍会保留在树中，因此可以用作蒙版。
• 定位： boundingBox={{ x: { unit: 'px', value: 24 }, y: { unit: 'uv', value: 0.1 }, width: ..., height: ..., origin: 'top-left', rotation: 15 }}。uv 表示画布的 0–1 比例，px 表示 CSS 像素，调整大小后数值保持不变。
• Group 是一个容器。它的 flow 属性（{ mode: 'column' | 'row', gap, align }）会像 flexbox 一样排列其子项。
• 颜色属性接受 CSS 十六进制字符串。带有 colorSpace 属性的组件会在 linear、oklch、oklab、hsl、hsv 或 lch 中进行混合。oklab 和 oklch 能让渐变中点保持明亮。

动态属性

用带有 type 的对象替代数字或 {x, y} 值。无需编写动画代码：

<Circle radius={{ type: 'auto-animate', mode: 'ping-pong', outputMin: 0.2, outputMax: 0.6, speed: 1 }} />
<Circle center={{ type: 'mouse-position', smoothing: 0.12, momentum: 0.2 }} />
<Blur intensity={{ type: 'mouse', axis: 'x', outputMin: 0, outputMax: 40, smoothing: 0.1 }} />
<LinearGradient id="grad" colorA="#000000" colorB="#ffffff" />
<Circle radius={{ type: 'map', source: 'grad', channel: 'luminance', inputMin: 0, inputMax: 1, outputMin: 0.02, outputMax: 0.12 }} />

mouse-position 可驱动任何 {x, y} 属性（center、position、offset）。mouse 可将一个光标轴映射为数字。map 会按 id 读取另一个图层。框架状态也可用于任何属性，并会在下一帧更新，无需重新编译。

框架惯用写法

框架	导入	说明
React	shaders/react	使用 className；在渲染 <Shader> 的 Next.js 文件中添加 'use client'
Vue	shaders/vue	使用 kebab-case 属性，非字符串值使用 :（:angle="45"）；在 Nuxt 中用 <ClientOnly> 包裹
Svelte	shaders/svelte	使用普通属性；SvelteKit 无需额外配置，<Shader> 在服务器上不会渲染任何内容
Solid	shaders/solid	传入访问器值（angle={angle()}）；在 SolidStart 中通过 clientOnly 加载
Vanilla	shaders/js	createShader(canvas, { components: [{ type: 'Circle', props: {...}, children: [] }] })

Shaders 需要运行在支持 WebGPU 的浏览器中。它无法在服务器上渲染，因此在元框架中应确保 <Shader> 仅在客户端渲染。

示例

以下四种树形结构涵盖了大多数需求。属性均为实际值；可以修改数值，但请保留结构。

Hero 背景。 生成器以同级组件的形式堆叠，低不透明度的噪点可增加颗粒感，拖尾位于最上层：

<Shader className="absolute inset-0 -z-10">
  <MeshGradient colorA="#1a0533" colorB="#ffdf8e" colorSpace="oklab" speed={0.6} />
  <SimplexNoise scale={3} speed={0.5} opacity={0.12} blendMode="softLight" />
  <CursorTrail colorA="#ffffff" colorB="#e04b9e" radius={0.3} length={0.4} opacity={0.5} blendMode="screen" />
</Shader>

Logo 上的玻璃效果。 Glass 位于图像之后，因此会折射之前绘制的所有内容。形状是一个随光标移动的圆形 SDF：

<Shader className="w-full h-96">
  <ImageTexture url="/logo.png" objectFit="contain" />
  <Glass
    shape={{ type: 'circleSDF', radius: 0.35 }}
    center={{ type: 'mouse-position', smoothing: 0.15, momentum: 0.2 }}
    refraction={1.3}
    thickness={0.6}
    aberration={0.4}
    fresnel={0.25}
  />
</Shader>

文字后方的模糊图像。 使用平铺堆叠：图像，然后是 Blur，再然后是 Vignette，每个组件都会作用于其上方的内容。文字是通过 CSS 分层放置在画布上方的普通 HTML，不是组件：

<div className="relative">
  <Shader className="absolute inset-0 -z-10">
    <ImageTexture url="/hero.jpg" objectFit="cover" />
    <Blur intensity={60} />
    <Vignette intensity={0.8} radius={0.6} />
  </Shader>
  <h1 className="relative">Headline</h1>
</div>

蒙版揭示效果。 隐藏圆形，让它只用于塑造渐变。为 radius 添加动画即可揭示内容：

<Shader className="w-full h-64">
  <Circle id="reveal" visible={false} radius={{ type: 'auto-animate', mode: 'ping-pong', outputMin: 0.1, outputMax: 0.9, speed: 0.5 }} softness={0.2} />
  <LinearGradient colorA="#0f172a" colorB="#7c3aed" angle={45} colorSpace="oklch" maskSource="reveal" />
</Shader>

挑选组件

共 200 个组件，按类别划分：

• 纹理（55）：Aurora、Beam、Blob、BlockNoise、BlueNoise、BrickPattern、Checkerboard、Chevron、ColorWheel、ConicGradient、CurlNoise、DiamondGradient、DotGrid、ErosionNoise、FallingLines、FloatingParticles、FlowingGradient、FractalNoise、GaborNoise、Godrays、Grid、HexGrid、HTMLInCanvas、ImageTexture、IsometricCubes、LinearGradient、Marble、MeshGradient、MultiPointGradient、PerlinNoise、Plasma、Prism、RadialGradient、Ripples、Satin、Scratches、SimplexNoise、SineWave、SolidColor、Spiral、Strands、Stripes、StudioBackground、SunBurst、Swirl、Text、TriangularGrid、Truchet、VideoTexture、Voronoi、Waveform、WaveletNoise、Weave、WebcamTexture、WorleyNoise
• 形状（16）：Arc、Circle、Crescent、Cross、Ellipse、Flower、Heart、Line、Parallelogram、Polygon、Ring、RoundedRect、Star、Teardrop、Trapezoid、Vesica
• 形状效果（23）：BrushedMetal、CarbonFiber、Chrome、Crystal、Emboss、Frost、Glass、Goo、Heatmap、Hologram、Holographic、Irradiance、LightEdge、LiquidMetal、Nebula、Neon、Obsidian、Particles、Plastic、SmokeFill、ThinFilm、Voxels、Water
• 模糊（9）：AngularBlur、Blur、BokehBlur、ChannelBlur、DiffuseBlur、LinearBlur、ProgressiveBlur、TiltShift、ZoomBlur
• 扭曲（22）：BarShift、Bend、Bulge、ConcentricSpin、CornerPin、DisplacementMap、Flip、FlowField、FlutedGlass、Form3D、GlassTiles、Kaleidoscope、Mirror、Perspective、PolarCoordinates、RectangularCoordinates、Repeater、Spherize、Stretch、Surface3D、Twirl、WaveDistortion
• 调整（14）：BrightnessContrast、Duotone、Exposure、FilmStock、Grayscale、HueShift、Invert、Posterize、Saturation、Sharpness、Solarize、Tint、Tritone、Vibrance
• 风格化（31）：Ascii、Chalkboard、ChromaticAberration、CompressionArtifacts、ContourLines、CRTScreen、DataMosh、Dither、DropShadow、Engraving、FilmGrain、Glitch、Glow、GradientMap、Halftone、KeyFrames、LensDistortion、LensFlare、LightLeak、ObjectTracker、Paper、ParticleField、Pixelate、ReflectivePlane、Sparkle、Stone、TimeTrail、VHS、Vignette、Watercolor、Wool
• 交互（16）：Boids、ChromaFlow、CursorRipples、CursorTrail、Fog、GridDistortion、InkFlow、Liquify、MagneticFilings、ParticleFlow、PixelSort、PixelThrow、ReactionDiffusion、Shatter、Smoke、SmokeFlow
• 转场（13）：BarnDoors、BlockDissolve、CheckerWipe、DiamondWipe、IrisWipe、LinearWipe、NoiseDissolve、PagePeel、RadialWipe、RandomBars、RippleWipe、SliceWipe、VenetianBlinds
• 实用工具（1）：Group

此文件旁的 components.md 对每个组件都有一行说明，并标记了需要输入的效果。要查看组件的准确属性、默认值和范围，请使用 Accept: text/markdown 标头获取其文档页面：

https://shaders.com/docs/components/<Name>

完整参考文档汇总于一个文件中：https://shaders.com/llms-full.txt（内容较多）。指南见 https://shaders.com/docs/guide（关于组合、混合与遮罩、动态属性、布局、变换、形状效果和性能）。

形状效果（Glass、Neon、Chrome、LiquidMetal、Frost 等）会在 shape 属性内绘制：可以是 2D SDF，例如 { type: 'circleSDF', radius: 0.5 }，或 roundedRectSDF、starSDF、polygonSDF；也可以是 3D 实体，例如 { type: 'sphere3D' }、cube3D、torus3D；还可以是用户自己的 SVG 转换而成的 SDF 文件（MCP generate-sdf 工具可完成此操作）。参见 https://shaders.com/docs/guide/shape-effects。

预设和版块（Shaders Pro）

位于 https://shaders.com/presets 的预设库包含数千种设计好的效果，分属不同集合，另有完整的网站版块。每个预设页面都会显示其名称（集合 slug 加变体编号，例如 offsets-1）、实时渲染效果及其代码。安装预设需要登录的账户订阅 Shaders Pro：

npx shaders install offsets-1

如果没有 Pro，CLI 会说明情况，并提供打开定价页面、改用其他账户登录，或安装带水印的预览组件等选项，让用户查看预设的实际效果。账户开通 Pro 后，运行 npx shaders update 即可将预览替换为正式组件。不要绕过这项限制：告知用户该预设需要 Pro；如果用户想评估效果，就安装预览，然后继续处理。

如果要实现的视觉效果需要多个组件，请先搜索预设库，再从头构建。预设是经过设计和调整的组件树；如果有合适的预设，请说明这一点并告知其名称。

编写不存在的组件

如果没有组件或预设能实现所需效果，就编写一个组件。组件是传给 shaders/std 中 defineShader 的普通对象，包含名称、属性，以及每个像素的绘制方式；可以使用与库相同的基础图元构建，也可以直接编写 WGSL 主体。在任何框架中，都可通过 <CustomShader src={MyShader}> 挂载组件，无需构建步骤。请先阅读 https://shaders.com/docs/guide/custom-shaders 和基础图元参考文档：https://shaders.com/docs/primitives（也可以阅读 https://shaders.com/std/llms.txt 这份整合文档）。

保持效果运行流畅

• 使用生成器（渐变、噪声、等离子效果）构建背景；它们几乎不消耗性能。
• 将效果作为平级图层放在扁平堆栈中。嵌套每增加一层就会增加一次渲染，而平级效果已经覆盖此前绘制的所有内容。
• 使用 visible={false} 隐藏图层，而不是 opacity={0}。隐藏图层不会消耗性能；透明图层仍会渲染。
• 动画化运行时属性。少数属性属于编译时属性（组件页面会标明），更改后会重新编译效果。
• 离屏画布会自行降至约 1fps；对此无能为力。

不要

• 不要为组件已能实现的效果安装 three、@react-three/fiber、ogl，也不要编写原生 WebGL。
• 不要臆造属性名。先查看 components.md，再查看对应组件的文档页面。
• 如果平级堆栈能达到相同效果，就不要在效果内嵌套图层。仅在需要将效果限定到特定图层时才嵌套。
• 不要设置或查询内部的 <canvas>；其标记可能会随版本更新而变化。