rn-skia

React Native Skia — 最佳实践与性能指南

@shopify/react-native-skia 2.x / React Native >= 0.79 / React >= 19 / Reanimated v3+

关键规则

1. 绝不要在 JSX 渲染中读取 .value — 直接将共享值作为属性传递：<Circle cx={x} />，而不是 <Circle cx={x.value} />。
2. 绝不要在渲染过程中创建 Skia 对象 — 使用 useMemo 创建 Paint、Path、PictureRecorder、RuntimeEffect。
3. 始终在 useDerivedValue 回调中的 worklet 函数上标记 "worklet" 指令。
4. 动画化属性，而不是结构 — 保持组件树静态；只动画化数值/颜色属性。
5. 对于 10 个以上的相似元素，使用 Atlas — 单次绘制调用胜过 N 个独立组件。
6. 复用 Paint 和 PictureRecorder 对象 — 每帧创建对象会增加 GC 压力并导致掉帧。
7. UI 动画优先使用保留模式（FFI 开销近乎为零）；只有在绘制命令数量可变时（粒子、生成艺术、游戏）才使用即时模式（Picture API）。
8. 对于简单形状，优先使用 BlurMask 而不是 Blur — 开销更低。
9. 按开销从低到高排列滤镜 — 将 MatrixColorFilter 放在 Blur 之前。
10. 在组件层级加载字体/图片，使用 useFont/useImage — 渲染前处理加载状态为空的情况。

版本兼容性

React Native Skia	React Native	React	iOS	Android
2.x	>= 0.79	>= 19	>= 14	API >= 21
1.12.4	<= 0.78	<= 18	>= 14	API >= 21

视频支持需要 Android API 26+。

安装

npm install @shopify/react-native-skia
# Postinstall downloads prebuilt Skia binaries — must run
# Bun: bun add --trust @shopify/react-native-skia
# pnpm v10+: add to pnpm.onlyBuiltDependencies in package.json

iOS：cd ios && pod install。Android ProGuard：添加 -keep class com.shopify.reactnative.skia.** { *; }。

必要导入

import {
  Canvas, Circle, Rect, RoundedRect, Line, Path, Group, Fill,
  Text, Paragraph, Image, ImageSVG,
  LinearGradient, RadialGradient, SweepGradient,
  Blur, BlurMask, Shadow, BackdropBlur, MatrixColorFilter,
  RuntimeShader, FractalNoise, Turbulence, ImageShader,
  Atlas, Picture, Vertices, Patch, DiffRect, FitBox, Box,
  useFont, useImage, useSVG, useCanvasRef,
  Skia, vec, rect, rrect, drawAsImage,
  usePathInterpolation, useRSXformBuffer, useRectBuffer, useClock,
  interpolateColors,
} from "@shopify/react-native-skia";

import {
  useSharedValue, useDerivedValue, withTiming, withSpring,
  withRepeat, withSequence, withDelay, withDecay, cancelAnimation,
} from "react-native-reanimated";

核心模式 — 保留模式动画

const x = useSharedValue(0);
const scale = useSharedValue(1);

useEffect(() => {
  x.value = withSpring(200);
  scale.value = withSpring(1.5);
}, []);

return (
  <Canvas style={{ flex: 1 }}>
    <Group transform={[{ translateX: x }, { scale }]}>
      <Circle cx={0} cy={100} r={50} color="cyan" />
    </Group>
  </Canvas>
);

渲染模式选择

场景	模式	原因
UI 动画	保留模式	FFI 开销近乎为零，显示列表已缓存
图表与绘图	保留模式	结构静态，属性可动画化
粒子系统	即时模式	绘制命令数量可变
游戏	即时模式	每帧均可完全控制
生成艺术	即时模式	场景变化不可预测
混合	两者皆可	粒子使用 Picture，UI 使用 Group

性能速查

Fastest (use freely):      Circle, Rect, Line, Group transforms, MatrixColorFilter
Fast (use moderately):     Path (simple), BlurMask, LinearGradient
Slow (use sparingly):      BackdropBlur, RuntimeShader, DisplacementMap, Blur (large radius)

目标：60fps = 16.67ms 预算，120fps = 8.33ms 预算。内存 < 100MB。JS 线程 < 50%。

发现后立即修复的反模式

反模式	修复
JSX 中的 cx={x.value}	cx={x} — 直接传递共享值
在渲染主体中使用 Skia.Paint()	使用 useMemo(() => Skia.Paint(), []) 包装
在渲染主体中使用 Skia.Path.Make()	使用 useMemo 包装
对 10 个以上的元素使用 {items.map(i => <Circle .../>)}	使用 Atlas 和 useRSXformBuffer
<Blur blur={0} />	移除 — 无操作滤镜会浪费周期
每帧都变化的动态组件列表	使用即时模式（Picture API）
使用 useState 驱动 Skia 动画	使用 useSharedValue
useDerivedValue 中缺少 "worklet"	将指令作为第一条语句添加
未检查字体/图片是否为空	使用 if (!font) return null 进行保护
<BackdropBlur> 包裹大面积区域	限制裁剪区域，或使用 BlurMask

代码审查操作

收到审查/审计/检查 Skia 代码的请求时：

1. 扫描所有导入 @shopify/react-native-skia 的文件。
2. 对照关键规则和反模式表进行检查。
3. 以表格形式报告：| 文件 | 行 | 问题 | 严重性 | 修复方法 |
4. 严重性：CRITICAL（崩溃/渲染异常）、HIGH（掉帧）、MEDIUM（未充分优化）、LOW（风格问题）。
5. 如果确认存在问题，修复所有问题，然后重新扫描，确认违规项为零。

参考文件

根据需要阅读这些文件，了解详细的 API 文档、示例和模式：

• 入门指南：安装（npm/yarn/Expo/Bun/pnpm）、平台设置（iOS/Android/Web）、postinstall 脚本、Hello World、Canvas 组件、Skia 对象 API、项目结构、构建错误排查、包体积。
• Canvas 与渲染模式：保留模式（声明式组件、显示列表、几乎为零的 FFI）、即时模式（Picture API、PictureRecorder、直接绘制命令）、组合两种模式、离屏/无头渲染、Canvas 快照、自定义渲染器、平台注意事项。
• 形状与绘制：所有形状组件（Circle、Rect、RoundedRect、Oval、Line、Points、Fill、使用 SVG 表示法的 Path、Atlas/RSXform 精灵批处理、Vertices、Patch、DiffRect）、Group 变换/混合模式/裁剪、Paint 组件、FitBox、带阴影的 Box、路径裁剪动画。
• 动画：Reanimated v3 集成（将共享值作为直接属性）、动画类型（timing/spring/decay/repeat/sequence）、派生值、Skia hooks（usePathInterpolation、usePathValue、useClock、useRectBuffer、useRSXformBuffer）、颜色动画（interpolateColors）、手势集成（平移/捏合/旋转/多点触控）、完整示例（脉冲按钮、加载指示器、弹跳球）。
• 着色器与渐变：线性/径向/扫描/双点圆锥渐变、渐变动画、FractalNoise/Turbulence、自定义 SkSL 运行时着色器（波浪扭曲、色差、辉光、极光、水波纹）、ShaderLib 函数、ImageShader 纹理、着色器组合、性能（半精度、缓存程序）。
• 滤镜与效果：图像滤镜（Blur、Offset、Morphology、DisplacementMap、Shadow、RuntimeShader）、蒙版滤镜（BlurMask 样式：normal/solid/outer/inner）、颜色滤镜（包含灰度/棕褐色/反色/亮度/对比度矩阵的 MatrixColorFilter、BlendColor、LumaColorFilter、Lerp）、路径效果（Discrete、Dash、Corner、Path1D、Path2D、Line2D、Sum）、BackdropBlur/BackdropFilter、Mask（alpha/luminance）、磨砂玻璃/霓虹辉光/复古照片示例。
• 文本与字体：Text 组件（基线定位）、useFont hook、系统字体、matchFont、Paragraph 构建器（富文本、样式、对齐）、TextPath（沿曲线排列文本）、TextBlob、Glyphs、字体度量/测量、动画文本（位置、字号）、跑马灯/打字机/阴影示例。
• 图像与媒体：useImage hook（require/URL/bundle）、Image 组件（适配模式、采样）、以编程方式创建图像（base64、原始像素、drawAsImage）、图像处理（调整大小、编码、读取像素）、AnimatedImage（GIF/WebP）、SVG（useSVG、ImageSVG、从字符串创建）、视频播放（useVideo、控件）、Skottie/Lottie（动画、动态属性、插槽）、Canvas 快照、图像效果。
• 性能优化：渲染流水线（JS→UI→GPU）、60fps/120fps 帧预算、保留模式与即时模式的特性、动画性能（共享值、派生值、批处理、worklets）、组件结构优化（扁平树、Groups、静态 Pictures）、内存管理（复用对象、释放图像、调整大小）、用于高性能渲染的 Atlas、滤镜成本层级、平台专属技巧（iOS Metal、Android OpenGL/androidWarmup、Web CanvasKit）、性能分析（useFrameCallback FPS 计数器、React DevTools、原生分析器）、常见问题检查清单。
• 高级模式：架构（组件组合、DrawingContext、原子/分子组件、自定义 hooks、render props）、实际示例（交互式柱状图、使用 Atlas 的粒子系统、带手势的绘图画布、进度环、波形可视化器）、设计系统集成（使用 Skia 颜色的主题提供器）、测试（单元测试、视觉回归）、调试（可视化网格叠加层、性能监视器）、常见模式（骨架屏加载、涟漪效果、彩纸屑）。