React Scan 在 Next.js Page Router 中的接入指南script 标签与模块导入两种方式详解【免费下载链接】react-scanScan and fix React performance issues项目地址: https://gitcode.com/GitHub_Trending/re/react-scan本篇技术指南以 React Scan 官方文档中的 Next.js Page Router 安装指南 为主体详细讲解如何在基于Pages Routerpages/目录的 Next.js 应用中接入 React Scan以扫描并定位 React 组件的重复渲染与性能瓶颈。读完本文你将掌握两种接入方式pages/_document中的 CDN script 标签、pages/_app中的模块导入、如何在生产环境强制启用扫描react-scan/all-environments并能理解其仅开发环境生效的底层判定逻辑从而避免踩坑。适用前提React Scanreact-scan包当前仓库版本为0.5.7见 packages/scan/package.json通过 React DevTools Hook基于bippy在运行时自动检测 React 渲染行为无需改动业务组件代码。其 peerDependencies 声明支持react/react-dom的^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0因此 Pages Router 下无论是 Next.js 12、13、14 还是 15 的项目只要满足上述 React 版本要求即可接入。本文针对的是Page Routerpages/目录如果你的项目使用 App Routerapp/目录请参考 App Router 安装指南。方式一通过 CDN script 标签接入这是最快的接入方式——不需要安装任何 npm 包只需要在pages/_document中添加一个 script 标签。修改pages/_document打开或创建pages/_document将 React Scan 的auto.global.js以script标签引入到Head中// pages/_document import { Html, Head, Main, NextScript } from next/document; export default function Document() { return ( Html langen Head script srchttps://unpkg.com/react-scan/dist/auto.global.js / {/* 其余脚本放在下面 */} /Head body Main / NextScript / /body /Html ); }之所以放在pages/_document的Head里是因为_document只在服务端渲染时执行最终生成的auto.global.js会随首屏 HTML 一并下发从而保证脚本在应用 JavaScript 执行前就绪。可用的 CDN 地址官方 CDN 指南 提供以下两个等价地址任选其一!-- JSDelivr -- script srchttps://cdn.jsdelivr.net/npm/react-scan/dist/auto.global.js/script !-- UNPKG -- script srchttps://unpkg.com/react-scan/dist/auto.global.js/scriptauto.global.js 做了什么auto.global.js对应源码 packages/scan/src/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; }即在客户端环境下自动调用scan()完成初始化无需任何手动配置同时把scan挂到window.reactScan上方便在浏览器控制台里随时手动开关扫描。这正是 script 标签方式开箱即用的原因。方式二通过模块导入接入如果你更希望把依赖纳入 npm 管理而非 CDN可以采用模块导入方式。首先安装npm install react-scan # 或 pnpm add react-scan然后在pages/_app中完成初始化。修改pages/_app// pages/_app // react-scan 必须是文件中最顶部的导入 import { scan } from react-scan; import { useEffect } from react; export default function App({ Component, pageProps }) { useEffect(() { // 确保在 React 水合hydration完成之后再启动扫描 scan({ enabled: true, }); }, []); return Component {...pageProps} /; }这里有两点必须注意import { scan } from react-scan必须是文件中最顶部的导入。React Scan 依赖bippy的副作用来安装 React 内部的 hook只有先于 React 相关模块执行才能在 React 渲染管线中挂上探针。若导入顺序不对控制台会在 5 秒后报出[React Scan] Failed to load. Must import React Scan before React runs.该逻辑见 packages/scan/src/core/index.ts。scan()必须放在useEffect中、即水合完成之后调用。在渲染阶段调用会干扰 React 的正常提交流程放在useEffect空依赖数组中可保证只在客户端、只在首次挂载后执行一次。在生产环境也启用扫描react-scan/all-environments默认情况下React Scan只在开发环境运行——这是由 packages/scan/src/core/index.ts 中start()的逻辑决定的当检测到当前 React 为生产构建getIsProduction()返回true且未开启dangerouslyForceRunInProduction时直接跳过初始化。如果你需要在生产环境例如线上复现性能问题也启用扫描把导入路径换成react-scan/all-environments- import { scan } from react-scan; import { scan } from react-scan/all-environments;该导出子路径在 packages/scan/package.json 中声明其实现位于 packages/scan/src/core/all-environments.tsimport { ReactScanInternals, scan as innerScan } from .; export const scan /*#__PURE__*/ (...params: Parameterstypeof innerScan) { if (typeof window ! undefined) { ReactScanInternals.runInAllEnvironments true; innerScan(...params); } };原理很简单调用前先把内部标志ReactScanInternals.runInAllEnvironments置为truestart()中的环境检查见 packages/scan/src/core/index.ts便会跳过生产环境拦截从而实现任意环境开发、生产、iframe都能扫描。script 标签方式没有等价的生产开关如需生产扫描请使用模块导入方式。源码级原理解析scan() 的完整调用链模块导入方式触发的核心调用链为scan(options)→setOptions(options)start()均位于 packages/scan/src/core/index.tsexport const scan (options: Options {}) { setOptions(options); const isInIframe Store.isInIframe.value; if ( isInIframe !ReactScanInternals.options.value.allowInIframe !ReactScanInternals.runInAllEnvironments ) { return; } if (options.enabled false options.showToolbar ! true) { return; } start(); };可以看到三个关键判定iframe 保护默认allowInIframe为false在 iframe 内默认不启动除非显式开启或使用all-environments显式关闭enabled: false且未要求显示工具栏时直接返回环境门槛start()内通过getIsProduction()判断当前 React 是否为生产构建见 packages/scan/src/core/index.ts。值得注意的一个细节getIsProduction()对检测到开发构建的结果做了永久缓存但故意不缓存生产构建的结果。其测试用例 packages/scan/src/core/get-is-production.test.ts 注释了原因——Next.js 的 dev overlay 会先注册一个生产版 React 渲染器随后用户的开发版 React 才在下一 tick 注册若把首次的true缓存下来就会把 dev 环境误判为生产而锁死扫描。这个边界情况正是 Next.js 项目中最容易踩到的坑也是官方通过回归测试专门防护的。常用配置项在pages/_app中调用scan()时传入的Options定义于 packages/scan/src/core/index.ts常用项及默认值如下配置项类型默认值说明enabledbooleantrue是否启用扫描推荐写成process.env.NODE_ENV developmentshowToolbarbooleantrue是否显示右下角工具栏设为true时即使enabled: false工具栏仍显示但扫描关闭animationSpeedslow \| fast \| offfast渲染高亮动画速度logbooleanfalse将渲染日志打印到控制台注意频繁渲染时会带来明显开销trackUnnecessaryRendersbooleanfalse追踪无效渲染组件重渲染但 DOM 子树无变化并以灰色轮廓标记会带来额外开销showFPSbooleantrue工具栏中是否显示 FPS 计数器showNotificationCountbooleantrue工具栏中是否显示性能提醒数量allowInIframebooleanfalse是否允许在 iframe 内运行safeAreanumber \| { top?, right?, bottom?, left? }24工具栏距视口边缘的像素距离可避免与 Next.js dev indicator 等覆盖层重叠dangerouslyForceRunInProductionbooleanfalse强制在生产环境运行不推荐优先使用all-environments导入一个推荐的开发环境写法import { scan } from react-scan; import { useEffect } from react; export default function App({ Component, pageProps }) { useEffect(() { scan({ enabled: process.env.NODE_ENV development, trackUnnecessaryRenders: true, }); }, []); return Component {...pageProps} /; }注意setOptions会通过validateOptions校验传入项见 packages/scan/src/core/index.ts非法值如animationSpeed传了normal不会生效并会在控制台输出[React Scan] Invalid options警告enabled等布尔选项同时会被持久化到localStorage键名react-scan-options因此刷新页面后开关状态会保留。常见问题排查控制台出现[React Scan] Failed to load. Must import React Scan before React runs.说明react-scan的导入不在最顶部或 script 标签加载晚于 React 执行。请调整导入顺序或改用pages/_document的 CDN 方式。生产环境没有高亮效果这是预期行为——默认仅开发环境生效。需要生产扫描请改用react-scan/all-environments。页面在 iframe 中无扫描效果默认allowInIframe: false若目标场景在 iframe 中请显式开启该选项。工具栏与 Next.js 自带开发指示器重叠使用safeArea配置项调整工具栏的安全间距。小结在 Next.js Page Router 项目中接入 React Scan 共有两条路径CDN script 标签零依赖、修改pages/_document即可与模块导入纳入 npm 管理、修改pages/_app。两者都遵循同一底层实现——通过bippy安装 React hook、scan()完成初始化的调用链并默认只在开发环境生效如需生产环境扫描模块导入方式可无缝切换到react-scan/all-environments。接入之后组件每次渲染都会以高亮轮廓的形式呈现在页面上配合工具栏的 FPS 与渲染统计即可快速定位谁在渲染、为什么渲染。【免费下载链接】react-scanScan and fix React performance issues项目地址: https://gitcode.com/GitHub_Trending/re/react-scan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
React Scan 在 Next.js Page Router 中的接入指南script 标签与模块导入两种方式详解【免费下载链接】react-scanScan and fix React performance issues项目地址: https://gitcode.com/GitHub_Trending/re/react-scan本篇技术指南以 React Scan 官方文档中的 Next.js Page Router 安装指南 为主体详细讲解如何在基于Pages Routerpages/目录的 Next.js 应用中接入 React Scan以扫描并定位 React 组件的重复渲染与性能瓶颈。读完本文你将掌握两种接入方式pages/_document中的 CDN script 标签、pages/_app中的模块导入、如何在生产环境强制启用扫描react-scan/all-environments并能理解其仅开发环境生效的底层判定逻辑从而避免踩坑。适用前提React Scanreact-scan包当前仓库版本为0.5.7见 packages/scan/package.json通过 React DevTools Hook基于bippy在运行时自动检测 React 渲染行为无需改动业务组件代码。其 peerDependencies 声明支持react/react-dom的^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0因此 Pages Router 下无论是 Next.js 12、13、14 还是 15 的项目只要满足上述 React 版本要求即可接入。本文针对的是Page Routerpages/目录如果你的项目使用 App Routerapp/目录请参考 App Router 安装指南。方式一通过 CDN script 标签接入这是最快的接入方式——不需要安装任何 npm 包只需要在pages/_document中添加一个 script 标签。修改pages/_document打开或创建pages/_document将 React Scan 的auto.global.js以script标签引入到Head中// pages/_document import { Html, Head, Main, NextScript } from next/document; export default function Document() { return ( Html langen Head script srchttps://unpkg.com/react-scan/dist/auto.global.js / {/* 其余脚本放在下面 */} /Head body Main / NextScript / /body /Html ); }之所以放在pages/_document的Head里是因为_document只在服务端渲染时执行最终生成的auto.global.js会随首屏 HTML 一并下发从而保证脚本在应用 JavaScript 执行前就绪。可用的 CDN 地址官方 CDN 指南 提供以下两个等价地址任选其一!-- JSDelivr -- script srchttps://cdn.jsdelivr.net/npm/react-scan/dist/auto.global.js/script !-- UNPKG -- script srchttps://unpkg.com/react-scan/dist/auto.global.js/scriptauto.global.js 做了什么auto.global.js对应源码 packages/scan/src/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; }即在客户端环境下自动调用scan()完成初始化无需任何手动配置同时把scan挂到window.reactScan上方便在浏览器控制台里随时手动开关扫描。这正是 script 标签方式开箱即用的原因。方式二通过模块导入接入如果你更希望把依赖纳入 npm 管理而非 CDN可以采用模块导入方式。首先安装npm install react-scan # 或 pnpm add react-scan然后在pages/_app中完成初始化。修改pages/_app// pages/_app // react-scan 必须是文件中最顶部的导入 import { scan } from react-scan; import { useEffect } from react; export default function App({ Component, pageProps }) { useEffect(() { // 确保在 React 水合hydration完成之后再启动扫描 scan({ enabled: true, }); }, []); return Component {...pageProps} /; }这里有两点必须注意import { scan } from react-scan必须是文件中最顶部的导入。React Scan 依赖bippy的副作用来安装 React 内部的 hook只有先于 React 相关模块执行才能在 React 渲染管线中挂上探针。若导入顺序不对控制台会在 5 秒后报出[React Scan] Failed to load. Must import React Scan before React runs.该逻辑见 packages/scan/src/core/index.ts。scan()必须放在useEffect中、即水合完成之后调用。在渲染阶段调用会干扰 React 的正常提交流程放在useEffect空依赖数组中可保证只在客户端、只在首次挂载后执行一次。在生产环境也启用扫描react-scan/all-environments默认情况下React Scan只在开发环境运行——这是由 packages/scan/src/core/index.ts 中start()的逻辑决定的当检测到当前 React 为生产构建getIsProduction()返回true且未开启dangerouslyForceRunInProduction时直接跳过初始化。如果你需要在生产环境例如线上复现性能问题也启用扫描把导入路径换成react-scan/all-environments- import { scan } from react-scan; import { scan } from react-scan/all-environments;该导出子路径在 packages/scan/package.json 中声明其实现位于 packages/scan/src/core/all-environments.tsimport { ReactScanInternals, scan as innerScan } from .; export const scan /*#__PURE__*/ (...params: Parameterstypeof innerScan) { if (typeof window ! undefined) { ReactScanInternals.runInAllEnvironments true; innerScan(...params); } };原理很简单调用前先把内部标志ReactScanInternals.runInAllEnvironments置为truestart()中的环境检查见 packages/scan/src/core/index.ts便会跳过生产环境拦截从而实现任意环境开发、生产、iframe都能扫描。script 标签方式没有等价的生产开关如需生产扫描请使用模块导入方式。源码级原理解析scan() 的完整调用链模块导入方式触发的核心调用链为scan(options)→setOptions(options)start()均位于 packages/scan/src/core/index.tsexport const scan (options: Options {}) { setOptions(options); const isInIframe Store.isInIframe.value; if ( isInIframe !ReactScanInternals.options.value.allowInIframe !ReactScanInternals.runInAllEnvironments ) { return; } if (options.enabled false options.showToolbar ! true) { return; } start(); };可以看到三个关键判定iframe 保护默认allowInIframe为false在 iframe 内默认不启动除非显式开启或使用all-environments显式关闭enabled: false且未要求显示工具栏时直接返回环境门槛start()内通过getIsProduction()判断当前 React 是否为生产构建见 packages/scan/src/core/index.ts。值得注意的一个细节getIsProduction()对检测到开发构建的结果做了永久缓存但故意不缓存生产构建的结果。其测试用例 packages/scan/src/core/get-is-production.test.ts 注释了原因——Next.js 的 dev overlay 会先注册一个生产版 React 渲染器随后用户的开发版 React 才在下一 tick 注册若把首次的true缓存下来就会把 dev 环境误判为生产而锁死扫描。这个边界情况正是 Next.js 项目中最容易踩到的坑也是官方通过回归测试专门防护的。常用配置项在pages/_app中调用scan()时传入的Options定义于 packages/scan/src/core/index.ts常用项及默认值如下配置项类型默认值说明enabledbooleantrue是否启用扫描推荐写成process.env.NODE_ENV developmentshowToolbarbooleantrue是否显示右下角工具栏设为true时即使enabled: false工具栏仍显示但扫描关闭animationSpeedslow \| fast \| offfast渲染高亮动画速度logbooleanfalse将渲染日志打印到控制台注意频繁渲染时会带来明显开销trackUnnecessaryRendersbooleanfalse追踪无效渲染组件重渲染但 DOM 子树无变化并以灰色轮廓标记会带来额外开销showFPSbooleantrue工具栏中是否显示 FPS 计数器showNotificationCountbooleantrue工具栏中是否显示性能提醒数量allowInIframebooleanfalse是否允许在 iframe 内运行safeAreanumber \| { top?, right?, bottom?, left? }24工具栏距视口边缘的像素距离可避免与 Next.js dev indicator 等覆盖层重叠dangerouslyForceRunInProductionbooleanfalse强制在生产环境运行不推荐优先使用all-environments导入一个推荐的开发环境写法import { scan } from react-scan; import { useEffect } from react; export default function App({ Component, pageProps }) { useEffect(() { scan({ enabled: process.env.NODE_ENV development, trackUnnecessaryRenders: true, }); }, []); return Component {...pageProps} /; }注意setOptions会通过validateOptions校验传入项见 packages/scan/src/core/index.ts非法值如animationSpeed传了normal不会生效并会在控制台输出[React Scan] Invalid options警告enabled等布尔选项同时会被持久化到localStorage键名react-scan-options因此刷新页面后开关状态会保留。常见问题排查控制台出现[React Scan] Failed to load. Must import React Scan before React runs.说明react-scan的导入不在最顶部或 script 标签加载晚于 React 执行。请调整导入顺序或改用pages/_document的 CDN 方式。生产环境没有高亮效果这是预期行为——默认仅开发环境生效。需要生产扫描请改用react-scan/all-environments。页面在 iframe 中无扫描效果默认allowInIframe: false若目标场景在 iframe 中请显式开启该选项。工具栏与 Next.js 自带开发指示器重叠使用safeArea配置项调整工具栏的安全间距。小结在 Next.js Page Router 项目中接入 React Scan 共有两条路径CDN script 标签零依赖、修改pages/_document即可与模块导入纳入 npm 管理、修改pages/_app。两者都遵循同一底层实现——通过bippy安装 React hook、scan()完成初始化的调用链并默认只在开发环境生效如需生产环境扫描模块导入方式可无缝切换到react-scan/all-environments。接入之后组件每次渲染都会以高亮轮廓的形式呈现在页面上配合工具栏的 FPS 与渲染统计即可快速定位谁在渲染、为什么渲染。【免费下载链接】react-scanScan and fix React performance issues项目地址: https://gitcode.com/GitHub_Trending/re/react-scan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
