Create React App 项目中接入 React Scan 的完整指南script 标签与模块导入两种方式【免费下载链接】react-scanScan and fix React performance issues项目地址: https://gitcode.com/GitHub_Trending/re/react-scanReact Scan 是一款无需改动业务代码即可自动检测 React 应用渲染性能问题的开源工具它会高亮每一次组件渲染帮助你一眼定位需要优化的组件。本文基于仓库中的 docs/installation/create-react-app.md 官方安装文档系统讲解如何在 Create React AppCRA项目中接入 React Scan覆盖 script 标签与模块导入两种接入方式、生产环境运行开关以及底层源码实现原理。读完本文你将掌握在 CRA 项目中从零接入 React Scan 的全部实操步骤并理解“必须先于 React 导入”这一关键约束背后的机制。接入方式概览React Scan 为 CRA 这类传统的 webpack Babel 工程提供了两种接入路径二者选其一即可方式修改位置适用场景Script 标签index.htmlCRA 中为public/index.html零代码改动、不想侵入构建链路或希望按环境条件性加载模块导入项目入口文件如src/index.jsx、src/main.jsx需要编程式控制scan()的配置项或将扫描纳入模块化工程官方文档默认的示例文件名为index.html与src/index在标准 CRA 脚手架中前者对应public/index.html后者对应src/index.jsx。两种方式都可以在仓库的kitchen-sink/index.html与kitchen-sink/src/main.tsx中看到与之对应的典型入口结构。方式一通过 script 标签接入零代码改动在项目根 HTML 的head中、其他所有脚本之前插入如下标签!doctype html html langen head script srchttps://unpkg.com/react-scan/dist/auto.global.js/script !-- rest of your scripts go under -- /head body !-- ... -- /body /html可用的 CDN 地址官方 CDN 指南 提供了两个等价地址任选其一https://cdn.jsdelivr.net/npm/react-scan/dist/auto.global.js https://unpkg.com/react-scan/dist/auto.global.js推荐将脚本放在head的最顶部确保它先于应用自身的任何脚本执行。auto.global.js 自动模式的工作原理auto.global.js是打包产物中的IIFE 自执行包其构建入口是 packages/scan/src/auto.ts。从源码可以看到它做了三件事引入polyfills与bippy——其中bippy的副作用代码会抢先安装 React DevTools hook在浏览器环境下自动调用scan()无需任何手工初始化将scan暴露到全局window.reactScan方便在控制台随时手动调用。对应源码auto.tsimport ./polyfills; // Prioritize bippy side-effect import bippy; import { IS_CLIENT } from ~web/utils/constants; import { scan } from ./index; if (IS_CLIENT) { scan(); window.reactScan scan; } export * from ./core;也就是说通过 script 标签接入时React Scan 会以默认配置自动开始扫描你什么都不用写。而dist/auto.global.js这一产物名称也印证在 tsup.config.ts 中它由src/auto.ts以 IIFE 格式、目标 ES2019 构建ES2019 目标是为了兼容未配置babel/preset-env可选链语法的旧版 babel-loader 配置。方式二通过模块导入接入可编程控制如果你需要精细控制扫描行为可以在项目入口文件中显式导入并调用scan()// src/index.jsx // must be imported before React and React DOM import { scan } from react-scan; import React from react; scan({ enabled: true, });[!CAUTION] React Scan 必须在你整个项目中React以及 React DOM 等渲染器之前导入因为它需要在 React 拿到 DevTools hook 之前抢先劫持它。为什么必须最先导入hook 劫持机制这个约束不是凭空约定的而是由实现决定的。react-scan包的入口 packages/scan/src/index.ts 第一行就import bippy利用 bippy 的副作用在模块加载阶段安装 hook如果 React 已经先一步占用了 React DevTools 通道React Scan 将无法注入自己的 instrument。若你在 React 之后才导入控制台会在约 5 秒后收到一条明确的错误提示。这段兜底检测逻辑位于 packages/scan/src/core/index.tssetTimeout(() { if (isInstrumentationActive()) return; console.error([React Scan] Failed to load. Must import React Scan before React runs.); }, 5000);所以在 CRA 的src/index.jsx中请确保import { scan } from react-scan位于import React from react之前。scan() 的常用配置项scan()接收一个Options对象其完整定义在 packages/scan/src/core/index.ts。结合源码整理出最常用的配置项配置项类型默认值说明enabledbooleantrue是否启用扫描官方推荐写法enabled: process.env.NODE_ENV developmentlogbooleanfalse将渲染日志输出到控制台频繁重渲染时会产生显著开销谨慎开启showToolbarbooleantrue是否显示工具条即使enabled: false只要showToolbar: true工具条仍会显示仅停止扫描animationSpeedslow \| fast \| offfast高亮动画速度trackUnnecessaryRendersbooleanfalse跟踪“无必要渲染”组件重渲染但其 DOM 子树无变化以灰色轮廓标记会带来可观开销dangerouslyForceRunInProductionbooleanfalse强制在生产环境运行不推荐showFPSbooleantrue工具条中是否显示 FPS 表showNotificationCountbooleantrue工具条中是否显示慢渲染通知计数allowInIframebooleanfalse是否允许在 iframe 内运行safeAreanumber \| { top?; right?; bottom?; left? }24工具条距视口边缘的像素距离可避免与 Next.js 开发指示器等覆盖层重叠useOffscreenCanvasWorkerbooleantrue是否通过 OffscreenCanvas Web Worker 渲染轮廓若 CSP 不含worker-src blob:会禁用并自动回退到主线程onCommitStart/onRender/onCommitFinish回调函数—commit 生命周期钩子onRender可拿到 fiber 与渲染数据传入的配置会经过 setOptions 中的validateOptions校验布尔型字段、animationSpeed枚举、safeArea格式以及回调函数类型都会被逐一验证非法值会以[React Scan] Invalid options:前缀输出警告同时合法配置会被持久化到localStoragekey 为react-scan-options下次刷新依然生效。让 React Scan 在生产环境也运行默认情况下React Scan不会在生产环境运行。其判定逻辑在 getIsProduction它通过 bippy 的detectReactBuildType检查已注册渲染器的构建类型一旦确认是非生产渲染器就永久缓存“开发环境”结论而 start 会据此短路返回if ( !ReactScanInternals.runInAllEnvironments getIsProduction() !ReactScanInternals.options.value.dangerouslyForceRunInProduction ) { return; }如果你希望生产环境也执行扫描官方文档提供了react-scan/all-environments导入路径只需一行 diff- import { scan } from react-scan; import { scan } from react-scan/all-environments;该子路径在 packages/scan/package.json 的exports中声明其实现在 packages/scan/src/core/all-environments.tsexport const scan (...params) { if (typeof window ! undefined) { ReactScanInternals.runInAllEnvironments true; innerScan(...params); } };它的本质是把内部的runInAllEnvironments置为true从而绕过上面的生产环境短路检查。与之对比dangerouslyForceRunInProduction: true走的是另一条分支。两者都能在生产运行但官方明确提示生产环境运行“不推荐”请自行评估性能开销。接入后的验证与常见问题排查如何确认接入成功打开应用后页面上应出现 React Scan 的工具条组件渲染时会被高亮轮廓标记在控制台执行window.reactScanscript 标签方式可手动调用scan()重新触发扫描。常见问题Q1控制台报错 Failed to load. Must import React Scan before React runs.说明 React Scan 的导入晚于 React。检查src/index.jsx中 import 的顺序确保react-scan位于react/react-dom之前使用 script 标签时确保标签位于head顶部、任何应用脚本之前。Q2应用跑在 iframe 里扫描没有生效React Scan 默认禁止在 iframe 中运行见 scan 函数 对Store.isInIframe的判断。若确有需要传入allowInIframe: true。Q3生产环境不扫描这是默认行为。如需生产运行改用react-scan/all-environments导入路径或设置dangerouslyForceRunInProduction: true。Q4项目 React 版本是否兼容根据 packages/scan/package.json 的peerDependenciesreact-scan 支持react/react-dom的^16.8.0、^17.0.0、^18.0.0、^19.0.0CRA 3.x 及以上的默认 React 版本均在支持范围内。Q5CSP 严格限制导致轮廓无法渲染如果站点的 Content-Security-Policy 不允许worker-src blob:可将useOffscreenCanvasWorker: falseReact Scan 会自动回退到主线程渲染。小结在 Create React App 项目中接入 React Scan 只需一条 script 标签或一次入口文件的scan()调用script 标签方式在public/index.html的head顶部引入auto.global.js自动开始扫描零代码侵入模块导入方式在src/index.jsx的最顶部React 之前import { scan } from react-scan并调用scan({ enabled: process.env.NODE_ENV development })需要生产环境扫描时切换为react-scan/all-environments导入路径。接入后React Scan 会以高亮轮廓自动标记每一次组件渲染把“猜测性能瓶颈”变成“看见性能瓶颈”让你在 CRA 项目中快速定位并修复不必要的重渲染。【免费下载链接】react-scanScan and fix React performance issues项目地址: https://gitcode.com/GitHub_Trending/re/react-scan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Create React App 项目中接入 React Scan 的完整指南：script 标签与模块导入两种方式
Create React App 项目中接入 React Scan 的完整指南script 标签与模块导入两种方式【免费下载链接】react-scanScan and fix React performance issues项目地址: https://gitcode.com/GitHub_Trending/re/react-scanReact Scan 是一款无需改动业务代码即可自动检测 React 应用渲染性能问题的开源工具它会高亮每一次组件渲染帮助你一眼定位需要优化的组件。本文基于仓库中的 docs/installation/create-react-app.md 官方安装文档系统讲解如何在 Create React AppCRA项目中接入 React Scan覆盖 script 标签与模块导入两种接入方式、生产环境运行开关以及底层源码实现原理。读完本文你将掌握在 CRA 项目中从零接入 React Scan 的全部实操步骤并理解“必须先于 React 导入”这一关键约束背后的机制。接入方式概览React Scan 为 CRA 这类传统的 webpack Babel 工程提供了两种接入路径二者选其一即可方式修改位置适用场景Script 标签index.htmlCRA 中为public/index.html零代码改动、不想侵入构建链路或希望按环境条件性加载模块导入项目入口文件如src/index.jsx、src/main.jsx需要编程式控制scan()的配置项或将扫描纳入模块化工程官方文档默认的示例文件名为index.html与src/index在标准 CRA 脚手架中前者对应public/index.html后者对应src/index.jsx。两种方式都可以在仓库的kitchen-sink/index.html与kitchen-sink/src/main.tsx中看到与之对应的典型入口结构。方式一通过 script 标签接入零代码改动在项目根 HTML 的head中、其他所有脚本之前插入如下标签!doctype html html langen head script srchttps://unpkg.com/react-scan/dist/auto.global.js/script !-- rest of your scripts go under -- /head body !-- ... -- /body /html可用的 CDN 地址官方 CDN 指南 提供了两个等价地址任选其一https://cdn.jsdelivr.net/npm/react-scan/dist/auto.global.js https://unpkg.com/react-scan/dist/auto.global.js推荐将脚本放在head的最顶部确保它先于应用自身的任何脚本执行。auto.global.js 自动模式的工作原理auto.global.js是打包产物中的IIFE 自执行包其构建入口是 packages/scan/src/auto.ts。从源码可以看到它做了三件事引入polyfills与bippy——其中bippy的副作用代码会抢先安装 React DevTools hook在浏览器环境下自动调用scan()无需任何手工初始化将scan暴露到全局window.reactScan方便在控制台随时手动调用。对应源码auto.tsimport ./polyfills; // Prioritize bippy side-effect import bippy; import { IS_CLIENT } from ~web/utils/constants; import { scan } from ./index; if (IS_CLIENT) { scan(); window.reactScan scan; } export * from ./core;也就是说通过 script 标签接入时React Scan 会以默认配置自动开始扫描你什么都不用写。而dist/auto.global.js这一产物名称也印证在 tsup.config.ts 中它由src/auto.ts以 IIFE 格式、目标 ES2019 构建ES2019 目标是为了兼容未配置babel/preset-env可选链语法的旧版 babel-loader 配置。方式二通过模块导入接入可编程控制如果你需要精细控制扫描行为可以在项目入口文件中显式导入并调用scan()// src/index.jsx // must be imported before React and React DOM import { scan } from react-scan; import React from react; scan({ enabled: true, });[!CAUTION] React Scan 必须在你整个项目中React以及 React DOM 等渲染器之前导入因为它需要在 React 拿到 DevTools hook 之前抢先劫持它。为什么必须最先导入hook 劫持机制这个约束不是凭空约定的而是由实现决定的。react-scan包的入口 packages/scan/src/index.ts 第一行就import bippy利用 bippy 的副作用在模块加载阶段安装 hook如果 React 已经先一步占用了 React DevTools 通道React Scan 将无法注入自己的 instrument。若你在 React 之后才导入控制台会在约 5 秒后收到一条明确的错误提示。这段兜底检测逻辑位于 packages/scan/src/core/index.tssetTimeout(() { if (isInstrumentationActive()) return; console.error([React Scan] Failed to load. Must import React Scan before React runs.); }, 5000);所以在 CRA 的src/index.jsx中请确保import { scan } from react-scan位于import React from react之前。scan() 的常用配置项scan()接收一个Options对象其完整定义在 packages/scan/src/core/index.ts。结合源码整理出最常用的配置项配置项类型默认值说明enabledbooleantrue是否启用扫描官方推荐写法enabled: process.env.NODE_ENV developmentlogbooleanfalse将渲染日志输出到控制台频繁重渲染时会产生显著开销谨慎开启showToolbarbooleantrue是否显示工具条即使enabled: false只要showToolbar: true工具条仍会显示仅停止扫描animationSpeedslow \| fast \| offfast高亮动画速度trackUnnecessaryRendersbooleanfalse跟踪“无必要渲染”组件重渲染但其 DOM 子树无变化以灰色轮廓标记会带来可观开销dangerouslyForceRunInProductionbooleanfalse强制在生产环境运行不推荐showFPSbooleantrue工具条中是否显示 FPS 表showNotificationCountbooleantrue工具条中是否显示慢渲染通知计数allowInIframebooleanfalse是否允许在 iframe 内运行safeAreanumber \| { top?; right?; bottom?; left? }24工具条距视口边缘的像素距离可避免与 Next.js 开发指示器等覆盖层重叠useOffscreenCanvasWorkerbooleantrue是否通过 OffscreenCanvas Web Worker 渲染轮廓若 CSP 不含worker-src blob:会禁用并自动回退到主线程onCommitStart/onRender/onCommitFinish回调函数—commit 生命周期钩子onRender可拿到 fiber 与渲染数据传入的配置会经过 setOptions 中的validateOptions校验布尔型字段、animationSpeed枚举、safeArea格式以及回调函数类型都会被逐一验证非法值会以[React Scan] Invalid options:前缀输出警告同时合法配置会被持久化到localStoragekey 为react-scan-options下次刷新依然生效。让 React Scan 在生产环境也运行默认情况下React Scan不会在生产环境运行。其判定逻辑在 getIsProduction它通过 bippy 的detectReactBuildType检查已注册渲染器的构建类型一旦确认是非生产渲染器就永久缓存“开发环境”结论而 start 会据此短路返回if ( !ReactScanInternals.runInAllEnvironments getIsProduction() !ReactScanInternals.options.value.dangerouslyForceRunInProduction ) { return; }如果你希望生产环境也执行扫描官方文档提供了react-scan/all-environments导入路径只需一行 diff- import { scan } from react-scan; import { scan } from react-scan/all-environments;该子路径在 packages/scan/package.json 的exports中声明其实现在 packages/scan/src/core/all-environments.tsexport const scan (...params) { if (typeof window ! undefined) { ReactScanInternals.runInAllEnvironments true; innerScan(...params); } };它的本质是把内部的runInAllEnvironments置为true从而绕过上面的生产环境短路检查。与之对比dangerouslyForceRunInProduction: true走的是另一条分支。两者都能在生产运行但官方明确提示生产环境运行“不推荐”请自行评估性能开销。接入后的验证与常见问题排查如何确认接入成功打开应用后页面上应出现 React Scan 的工具条组件渲染时会被高亮轮廓标记在控制台执行window.reactScanscript 标签方式可手动调用scan()重新触发扫描。常见问题Q1控制台报错 Failed to load. Must import React Scan before React runs.说明 React Scan 的导入晚于 React。检查src/index.jsx中 import 的顺序确保react-scan位于react/react-dom之前使用 script 标签时确保标签位于head顶部、任何应用脚本之前。Q2应用跑在 iframe 里扫描没有生效React Scan 默认禁止在 iframe 中运行见 scan 函数 对Store.isInIframe的判断。若确有需要传入allowInIframe: true。Q3生产环境不扫描这是默认行为。如需生产运行改用react-scan/all-environments导入路径或设置dangerouslyForceRunInProduction: true。Q4项目 React 版本是否兼容根据 packages/scan/package.json 的peerDependenciesreact-scan 支持react/react-dom的^16.8.0、^17.0.0、^18.0.0、^19.0.0CRA 3.x 及以上的默认 React 版本均在支持范围内。Q5CSP 严格限制导致轮廓无法渲染如果站点的 Content-Security-Policy 不允许worker-src blob:可将useOffscreenCanvasWorker: falseReact Scan 会自动回退到主线程渲染。小结在 Create React App 项目中接入 React Scan 只需一条 script 标签或一次入口文件的scan()调用script 标签方式在public/index.html的head顶部引入auto.global.js自动开始扫描零代码侵入模块导入方式在src/index.jsx的最顶部React 之前import { scan } from react-scan并调用scan({ enabled: process.env.NODE_ENV development })需要生产环境扫描时切换为react-scan/all-environments导入路径。接入后React Scan 会以高亮轮廓自动标记每一次组件渲染把“猜测性能瓶颈”变成“看见性能瓶颈”让你在 CRA 项目中快速定位并修复不必要的重渲染。【免费下载链接】react-scanScan and fix React performance issues项目地址: https://gitcode.com/GitHub_Trending/re/react-scan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考