用途
本指南面向使用 React Three Fiber（R3F）及 Poimandres 生态的开发者，用于在编写、审查或优化 R3F 代码时参考。内容覆盖 12 个规则分类，共 70 多条规则，按对性能与正确性的影响程度分为不同优先级，帮助定位并规避常见陷阱。
主要能力
指南按优先级组织规则：
- 性能与重渲染（CRITICAL）：禁止在 useFrame 中 setState、隔离需要 React 状态的组件、使用 Zustand 选择器、使用瞬态订阅、记忆化昂贵组件、为列表使用稳定 key、避免在 JSX 内联对象/数组、理解自动 dispose 行为、切换可见性而非重新挂载、使用 r3f-perf 监控性能。
- useFrame 与动画（CRITICAL）：使用 priority 控制执行顺序、始终使用 delta、按需禁用订阅、仅解构所需状态、使用 invalidate() 做按需渲染、将重计算移出 useFrame。
- 组件模式（HIGH）：用 JSX 表示 Three.js 对象、对非标准属性使用 attach、对已有对象使用 primitive、用 extend() 扩展自定义类、用 forwardRef 构建可复用组件、对共享资源设置 dispose={null}。
- Canvas 与初始化（HIGH）：Canvas 撑满父容器、通过 prop 配置相机、配置 WebGL 上下文、在 Canvas 层级启用阴影、选择合适的 frameloop 模式、配置事件处理、使用 linear/flat 保证正确颜色。
- Drei 助手（MEDIUM-HIGH）：useGLTF 与预加载、useTexture、Environment 光照、OrbitControls、Html 叠加、Text 三维文字、Instances 实例化、useHelper 调试、Bounds 适配相机、Center 居中、Float 浮动动画。
- 加载与 Suspense（MEDIUM-HIGH）：用 Suspense 包裹异步组件、useGLTF.preload 预加载、useProgress 加载 UI、懒加载重型组件、处理加载错误。
- 状态管理（MEDIUM）：创建聚焦的 Zustand store、谨慎处理 Three.js 对象、subscribeWithSelector 细粒度订阅、按需持久化、按关注点拆分 store。
- 事件与交互（MEDIUM）：在网格上使用指针事件、阻止事件冒泡、悬停时改变光标、过滤光线投射、理解事件数据结构。
- 后处理（MEDIUM）：使用 EffectComposer、常见效果参考、SelectiveBloom 优化发光、自定义 shader、优化后处理性能。
- 物理 Rapier（LOW-MEDIUM）：基础设置、物体类型 dynamic/fixed/kinematic、选择合适的碰撞体、碰撞事件、用 ref 访问物理 API、优化物理性能。
- Leva 调试 GUI（LOW）：基础用法、用 folders 组织、在生产环境隐藏。
使用方式
可按单条规则文件阅读详细说明与代码示例，例如 rules/perf-never-set-state-in-useframe.md、rules/drei-use-gltf.md、rules/state-zustand-selectors.md。完整展开版文档位于 ../R3F_BEST_PRACTICES.md。
指南中给出的关键示例包括：在 useFrame 中直接修改 ref 而非 setState、用 Zustand 选择器只订阅所需字段、useGLTF 加载模型并预加载、用 Suspense 处理异步加载、用 r3f-perf 监控、通过可见性切换代替重新挂载。
适用场景
编写新的 R3F 组件、排查或优化 R3F 渲染性能、正确使用 Drei 助手、用 Zustand 管理状态、实现后处理或物理效果等场景。
限制
资料未说明作者、许可、版本兼容范围、支持平台及维护状态，这些信息暂未提供。规则以建议形式给出，具体效果取决于项目上下文。