react-three/eslint-plugin 使用指南用 ESLint 规则杜绝 React Three Fiber 帧循环中的性能陷阱【免费下载链接】react-three-fiber A React renderer for Three.js项目地址: https://gitcode.com/GitHub_Trending/re/react-three-fiber导读本文围绕 react-three-fiber 仓库中 packages/eslint-plugin 这个官方 ESLint 插件展开讲解如何在 React Three Fiber 项目中通过静态检查自动发现并拦截useFrame帧循环中克隆向量实例化新对象两类典型的性能隐患。读完本文你将掌握该插件的安装方式、recommended与all两套共享配置的用法、两条核心规则的触发条件与修复范式并理解规则背后基于 AST 的实现原理与测试用例。为什么需要帧循环专用的 ESLint 规则React Three Fiber 的场景逻辑大量运行在useFrame回调中——这个回调在每个渲染帧通常每秒 60 次以上都会被调用。Three.js 中的Vector3、Quaternion、Matrix4等数学对象都是可变的 CPU 容器其构造与销毁成本远高于普通 JavaScript 对象每帧new一个对象一秒钟就会产生 60 次分配长时间运行会持续造成内存压力GPU 资源如BufferGeometry、Texture没有可靠的垃圾回收机制反复创建容易造成显存泄漏触发垃圾回收GC时会造成主线程卡顿直接表现为掉帧。这些是 React Three Fiber 场景中非常常见的性能反模式。通用 ESLint 规则无法理解useFrame的语义因此官方在 packages/eslint-plugin 中提供了专门面向该场景的插件。该包版本为 0.1.2在 package.json 中声明依赖eslint ^8.12.0作为开发依赖安装即可。安装与基础配置安装插件在项目根目录执行npm install react-three/eslint-plugin --save-dev安装完成后在 ESLint 配置中完成注册与规则启用。方式一使用共享配置推荐在.eslintrc或eslint.config对应的extends字段中加入{ extends: [ plugin:react-three/recommended ] }recommended配置会同时完成两件事注册react-three插件并把两条规则都设置为error级别。该配置的真实内容位于 src/configs/recommended.tsexport default { plugins: [react-three], rules: { react-three/no-clone-in-loop: error, react-three/no-new-in-loop: error, }, }方式二手动注册插件与规则如果不想使用共享配置也可以手动声明插件并逐条启用规则{ plugins: [react-three], rules: { react-three/no-clone-in-loop: error } }注意不通过共享配置时必须自行把react-three加入plugins否则规则无法生效。从 src/index.ts 可以看出插件导出rules与configs内含all和recommended两个入口这也是 ESLint 解析plugin:react-three/recommended时的底层依据。规则总览规则描述recommended可自动修复编辑器建议no-clone-in-loop禁止在帧循环中克隆向量避免性能问题✅no-new-in-loop禁止在帧循环中实例化新对象避免性能问题✅两条规则当前均不支持--fix自动修复与编辑器建议——因为如何消除分配依赖开发者对场景逻辑的判断无法安全地自动改写。规则列表由 scripts/codegen.ts 从源码生成README 中标注了yarn codegen:eslint命令。规则一no-clone-in-loop —— 禁止在帧循环中克隆向量问题场景Vector3等 Three.js 数学类的.clone()会返回一个全新的实例。如果把它放进useFrame就会每帧分配一个新对象function Direction({ targetPosition }) { const ref useRef() useFrame(() { const direction ref.current.position.clone().sub(targetPosition).normalize() }) return mesh ref{ref} / }这段代码每秒会创建 60 个以上的临时Vector3持续分配大量内存且每次帧回调结束后这些临时对象都要等待 GC 回收。正确写法一模块级共享引用在组件外部创建一次Vector3在帧循环中通过copy复用const tempVec new THREE.Vector3() function Direction({ targetPosition }) { const ref useRef() useFrame(() { const direction tempVec.copy(ref.current.position).sub(targetPosition).normalize() }) return mesh ref{ref} / }正确写法二useMemo 惰性创建如果希望实例跟随组件生命周期可以用useMemo只创建一次function Direction({ targetPosition }) { const ref useRef() const tempVec useMemo(() new THREE.Vector3()) useFrame(() { const direction tempVec.copy(ref.current.position).sub(targetPosition).normalize() }) return mesh ref{ref} / }两种写法的共同点是只在帧循环外分配一次对象帧循环内只做原地写入copy/set等。源码实现原理规则本体位于 src/rules/no-clone-in-loop.ts其核心是一个基于 AST 选择器的监听器[CallExpression[callee.nameuseFrame] CallExpression MemberExpression Identifier[nameclone]](node) { ctx.report({ messageId: noClone, node }) }该选择器含义是在useFrame(...)调用内部找到任意MemberExpression中名为clone的标识符调用并上报。也就是说只要clone出现在useFrame回调里无论被调用者是position、quaternion还是其他对象都会被标记为noClone错误。规则自带recommended: true标记这也是共享配置默认开启它的来源。测试用例验证no-clone-in-loop.test.ts 用 ESLint 官方RuleTester验证了规则行为合法valid模块级const vec new THREE.Vector3()后在useFrame中copy(vec)useFrame内调用普通函数clone()非成员方法局部变量名为clone的赋值等非法invaliduseFrame(() { ref.current.position.clone() })会命中noClone消息。这说明规则只针对useFrame上下文中的成员方法.clone()不会误伤函数名或变量名恰好叫clone的情况。规则二no-new-in-loop —— 禁止在帧循环中实例化新对象问题场景在useFrame中直接new THREE.Vector3(...)同样每帧产生新对象。对 Three.js 这类大体积 CPU 容器以及 GPU 资源如几何体、纹理而言尤其糟糕因为后者没有可靠的垃圾回收机制function MoveTowards({ x, y, z }) { const ref useRef() useFrame(() { ref.current.position.lerp(new THREE.Vector3(x, y, z), 0.1) }) return mesh ref{ref} / }正确写法一模块级共享引用用tempVec.set(x, y, z)原地写入替代newconst tempVec new THREE.Vector3() function MoveTowards({ x, y, z }) { const ref useRef() useFrame(() { ref.current.position.lerp(tempVec.set(x, y, z), 0.1) }) return mesh ref{ref} / }正确写法二useMemo 惰性创建function MoveTowards({ x, y, z }) { const ref useRef() const tempVec useMemo(() new THREE.Vector3()) useFrame(() { ref.current.position.lerp(tempVec.set(x, y, z), 0.1) }) return mesh ref{ref} / }源码实现原理src/rules/no-new-in-loop.ts 的选择器更加直接[CallExpression[callee.nameuseFrame] NewExpression](node) { ctx.report({ messageId: noNew, node }) }只要useFrame回调内部存在任何NewExpressionnew Xxx(...)表达式就上报noNew。这意味着该规则覆盖的不只是Vector3任何在帧循环里new出来的对象Quaternion、Matrix4、Group、BufferGeometry等都会被拦截。测试用例验证no-new-in-loop.test.ts 中合法valid在useFrame外new THREE.Vector3()后在帧内copy(vec)或lerp(vec.set(x, y, z), 0.1)使用未加THREE.前缀的new Vector3()同样合法因为new不在帧循环内非法invaliduseFrame内new THREE.Vector3(x, y, z)与new Vector3(x, y, z)两种写法都会命中noNew。可见规则对命名空间前缀THREE.与否不敏感判断依据纯粹是new表达式是否出现在useFrame内部。共享配置详解recommended推荐适合所有使用 React Three Fiber 的开发者包含当前全部两条规则且均为error级别{ extends: [plugin:react-three/recommended] }all全部规则all配置包含所有可用规则当前与recommended内容一致因为现有规则全部被标记为推荐{ extends: [plugin:react-three/all] }从 src/configs/all.ts 可以看到all同样注册了react-three插件并启用两条规则。将来插件新增未进入recommended的规则时all会成为无条件启用全部规则的选项。典型工作流与排查建议在实际项目中建议按以下步骤接入安装插件npm install react-three/eslint-plugin --save-dev在 ESLint 配置中加入plugin:react-three/recommended或手动注册插件 启用单条规则运行npx eslint src检查代码重点观察useFrame相关文件的报错参照本文的正确写法把clone()改为copy()、new Xxx()改为模块级或useMemo中的共享实例 原地set()写入将 ESLint 接入编辑器与 CI让帧循环性能问题在提交前暴露。规则当前不支持--fix自动修复因此推荐在编辑器保存时实时看到提示编辑器建议也暂未提供人工按上文模式重构。小结react-three/eslint-plugin通过两条 AST 级规则把帧循环中避免对象分配这一性能最佳实践固化成了可自动执行的静态检查no-clone-in-loop拦截useFrame中的.clone()成员调用no-new-in-loop拦截useFrame中的任何new表达式recommended/all两套共享配置开箱即用规则与配置的映射由 src/rules/index.ts 与 src/configs 统一导出。配合本文给出的模块级共享引用与useMemo一次性创建两种修复范式即可在代码层面显著降低 React Three Fiber 场景的内存分配与 GC 压力从源头规避掉帧与显存泄漏风险。【免费下载链接】react-three-fiber A React renderer for Three.js项目地址: https://gitcode.com/GitHub_Trending/re/react-three-fiber创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
react-three/eslint-plugin 使用指南用 ESLint 规则杜绝 React Three Fiber 帧循环中的性能陷阱【免费下载链接】react-three-fiber A React renderer for Three.js项目地址: https://gitcode.com/GitHub_Trending/re/react-three-fiber导读本文围绕 react-three-fiber 仓库中 packages/eslint-plugin 这个官方 ESLint 插件展开讲解如何在 React Three Fiber 项目中通过静态检查自动发现并拦截useFrame帧循环中克隆向量实例化新对象两类典型的性能隐患。读完本文你将掌握该插件的安装方式、recommended与all两套共享配置的用法、两条核心规则的触发条件与修复范式并理解规则背后基于 AST 的实现原理与测试用例。为什么需要帧循环专用的 ESLint 规则React Three Fiber 的场景逻辑大量运行在useFrame回调中——这个回调在每个渲染帧通常每秒 60 次以上都会被调用。Three.js 中的Vector3、Quaternion、Matrix4等数学对象都是可变的 CPU 容器其构造与销毁成本远高于普通 JavaScript 对象每帧new一个对象一秒钟就会产生 60 次分配长时间运行会持续造成内存压力GPU 资源如BufferGeometry、Texture没有可靠的垃圾回收机制反复创建容易造成显存泄漏触发垃圾回收GC时会造成主线程卡顿直接表现为掉帧。这些是 React Three Fiber 场景中非常常见的性能反模式。通用 ESLint 规则无法理解useFrame的语义因此官方在 packages/eslint-plugin 中提供了专门面向该场景的插件。该包版本为 0.1.2在 package.json 中声明依赖eslint ^8.12.0作为开发依赖安装即可。安装与基础配置安装插件在项目根目录执行npm install react-three/eslint-plugin --save-dev安装完成后在 ESLint 配置中完成注册与规则启用。方式一使用共享配置推荐在.eslintrc或eslint.config对应的extends字段中加入{ extends: [ plugin:react-three/recommended ] }recommended配置会同时完成两件事注册react-three插件并把两条规则都设置为error级别。该配置的真实内容位于 src/configs/recommended.tsexport default { plugins: [react-three], rules: { react-three/no-clone-in-loop: error, react-three/no-new-in-loop: error, }, }方式二手动注册插件与规则如果不想使用共享配置也可以手动声明插件并逐条启用规则{ plugins: [react-three], rules: { react-three/no-clone-in-loop: error } }注意不通过共享配置时必须自行把react-three加入plugins否则规则无法生效。从 src/index.ts 可以看出插件导出rules与configs内含all和recommended两个入口这也是 ESLint 解析plugin:react-three/recommended时的底层依据。规则总览规则描述recommended可自动修复编辑器建议no-clone-in-loop禁止在帧循环中克隆向量避免性能问题✅no-new-in-loop禁止在帧循环中实例化新对象避免性能问题✅两条规则当前均不支持--fix自动修复与编辑器建议——因为如何消除分配依赖开发者对场景逻辑的判断无法安全地自动改写。规则列表由 scripts/codegen.ts 从源码生成README 中标注了yarn codegen:eslint命令。规则一no-clone-in-loop —— 禁止在帧循环中克隆向量问题场景Vector3等 Three.js 数学类的.clone()会返回一个全新的实例。如果把它放进useFrame就会每帧分配一个新对象function Direction({ targetPosition }) { const ref useRef() useFrame(() { const direction ref.current.position.clone().sub(targetPosition).normalize() }) return mesh ref{ref} / }这段代码每秒会创建 60 个以上的临时Vector3持续分配大量内存且每次帧回调结束后这些临时对象都要等待 GC 回收。正确写法一模块级共享引用在组件外部创建一次Vector3在帧循环中通过copy复用const tempVec new THREE.Vector3() function Direction({ targetPosition }) { const ref useRef() useFrame(() { const direction tempVec.copy(ref.current.position).sub(targetPosition).normalize() }) return mesh ref{ref} / }正确写法二useMemo 惰性创建如果希望实例跟随组件生命周期可以用useMemo只创建一次function Direction({ targetPosition }) { const ref useRef() const tempVec useMemo(() new THREE.Vector3()) useFrame(() { const direction tempVec.copy(ref.current.position).sub(targetPosition).normalize() }) return mesh ref{ref} / }两种写法的共同点是只在帧循环外分配一次对象帧循环内只做原地写入copy/set等。源码实现原理规则本体位于 src/rules/no-clone-in-loop.ts其核心是一个基于 AST 选择器的监听器[CallExpression[callee.nameuseFrame] CallExpression MemberExpression Identifier[nameclone]](node) { ctx.report({ messageId: noClone, node }) }该选择器含义是在useFrame(...)调用内部找到任意MemberExpression中名为clone的标识符调用并上报。也就是说只要clone出现在useFrame回调里无论被调用者是position、quaternion还是其他对象都会被标记为noClone错误。规则自带recommended: true标记这也是共享配置默认开启它的来源。测试用例验证no-clone-in-loop.test.ts 用 ESLint 官方RuleTester验证了规则行为合法valid模块级const vec new THREE.Vector3()后在useFrame中copy(vec)useFrame内调用普通函数clone()非成员方法局部变量名为clone的赋值等非法invaliduseFrame(() { ref.current.position.clone() })会命中noClone消息。这说明规则只针对useFrame上下文中的成员方法.clone()不会误伤函数名或变量名恰好叫clone的情况。规则二no-new-in-loop —— 禁止在帧循环中实例化新对象问题场景在useFrame中直接new THREE.Vector3(...)同样每帧产生新对象。对 Three.js 这类大体积 CPU 容器以及 GPU 资源如几何体、纹理而言尤其糟糕因为后者没有可靠的垃圾回收机制function MoveTowards({ x, y, z }) { const ref useRef() useFrame(() { ref.current.position.lerp(new THREE.Vector3(x, y, z), 0.1) }) return mesh ref{ref} / }正确写法一模块级共享引用用tempVec.set(x, y, z)原地写入替代newconst tempVec new THREE.Vector3() function MoveTowards({ x, y, z }) { const ref useRef() useFrame(() { ref.current.position.lerp(tempVec.set(x, y, z), 0.1) }) return mesh ref{ref} / }正确写法二useMemo 惰性创建function MoveTowards({ x, y, z }) { const ref useRef() const tempVec useMemo(() new THREE.Vector3()) useFrame(() { ref.current.position.lerp(tempVec.set(x, y, z), 0.1) }) return mesh ref{ref} / }源码实现原理src/rules/no-new-in-loop.ts 的选择器更加直接[CallExpression[callee.nameuseFrame] NewExpression](node) { ctx.report({ messageId: noNew, node }) }只要useFrame回调内部存在任何NewExpressionnew Xxx(...)表达式就上报noNew。这意味着该规则覆盖的不只是Vector3任何在帧循环里new出来的对象Quaternion、Matrix4、Group、BufferGeometry等都会被拦截。测试用例验证no-new-in-loop.test.ts 中合法valid在useFrame外new THREE.Vector3()后在帧内copy(vec)或lerp(vec.set(x, y, z), 0.1)使用未加THREE.前缀的new Vector3()同样合法因为new不在帧循环内非法invaliduseFrame内new THREE.Vector3(x, y, z)与new Vector3(x, y, z)两种写法都会命中noNew。可见规则对命名空间前缀THREE.与否不敏感判断依据纯粹是new表达式是否出现在useFrame内部。共享配置详解recommended推荐适合所有使用 React Three Fiber 的开发者包含当前全部两条规则且均为error级别{ extends: [plugin:react-three/recommended] }all全部规则all配置包含所有可用规则当前与recommended内容一致因为现有规则全部被标记为推荐{ extends: [plugin:react-three/all] }从 src/configs/all.ts 可以看到all同样注册了react-three插件并启用两条规则。将来插件新增未进入recommended的规则时all会成为无条件启用全部规则的选项。典型工作流与排查建议在实际项目中建议按以下步骤接入安装插件npm install react-three/eslint-plugin --save-dev在 ESLint 配置中加入plugin:react-three/recommended或手动注册插件 启用单条规则运行npx eslint src检查代码重点观察useFrame相关文件的报错参照本文的正确写法把clone()改为copy()、new Xxx()改为模块级或useMemo中的共享实例 原地set()写入将 ESLint 接入编辑器与 CI让帧循环性能问题在提交前暴露。规则当前不支持--fix自动修复因此推荐在编辑器保存时实时看到提示编辑器建议也暂未提供人工按上文模式重构。小结react-three/eslint-plugin通过两条 AST 级规则把帧循环中避免对象分配这一性能最佳实践固化成了可自动执行的静态检查no-clone-in-loop拦截useFrame中的.clone()成员调用no-new-in-loop拦截useFrame中的任何new表达式recommended/all两套共享配置开箱即用规则与配置的映射由 src/rules/index.ts 与 src/configs 统一导出。配合本文给出的模块级共享引用与useMemo一次性创建两种修复范式即可在代码层面显著降低 React Three Fiber 场景的内存分配与 GC 压力从源头规避掉帧与显存泄漏风险。【免费下载链接】react-three-fiber A React renderer for Three.js项目地址: https://gitcode.com/GitHub_Trending/re/react-three-fiber创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
