React Native Debug Toolkit 使用文档

一个简单但功能强大的React Native调试工具包，提供便捷的开发期浮动界面。

安装

npm install react-native-debug-toolkit
# 或
yarn add react-native-debug-toolkit

iOS 额外设置

该工具包使用FLEX和DoraemonKit提供iOS调试功能。请按以下步骤正确集成：

1. 确保项目中已安装CocoaPods
2. 在Podfile中添加以下依赖：

pod 'FLEX', :configurations => ['Debug']   
pod 'DoraemonKit/Core', :git => 'https://github.com/superzcj/DoKit.git', :configurations => ['Debug'] #必选

3. 在didFinishLaunchingWithOptions方法中的AppDelegate.m文件中添加以下代码：

#ifdef DEBUG
#import <DoraemonKit/DoraemonManager.h>
#endif

  #ifdef DEBUG
  DoraemonManager *doKit = [DoraemonManager shareInstance];
  doKit.autoDock = false;
  [doKit install];
  [doKit hiddenDoraemon];
  #endif

4. 在iOS目录中运行pod install：

cd ios && pod install

Android 额外设置

1. 在android/settings.gradle中添加以下内容：

include ':react-native-debug-toolkit'
project(':react-native-debug-toolkit').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-debug-toolkit/android')

2. 在android/app/build.gradle中添加以下依赖：

dependencies {
    // 其他依赖...
    
    debugImplementation 'io.github.didi.dokit:dokitx:3.7.1'
    releaseImplementation 'io.github.didi.dokit:dokitx-no-op:3.7.1'
    debugImplementation 'com.android.volley:volley:1.2.0'
    
    implementation project(':react-native-debug-toolkit')
}

3. 在MainApplication.kt中初始化DoKit：

import com.didichuxing.doraemonkit.DoKit 
import com.reactnative.debuglibs.RNDebugLibsPackage

// 在getPackages方法内
add(RNDebugLibsPackage())

 // 在onCreate方法内
if (BuildConfig.DEBUG) {
    DoKit.Builder(this)
        .build()
    DoKit.hide()
}

使用方法

将调试工具包添加到您的应用程序中非常简单，只需一行代码即可启用所有功能：

// 在App.js或其他初始化文件中
import React, { useEffect } from 'react';
import { initializeDebugToolkit, isDebugMode } from 'react-native-debug-toolkit';

function App() {
  useEffect(() => {
    if (isDebugMode) {
      // 使用所有默认功能初始化
      initializeDebugToolkit();
      
      // 或选择特定的内置功能
      // initializeDebugToolkit(['network', 'console', 'zustand', 'navigation', 'thirdPartyLibs']);
    }
    
    return () => {
      // 自动清理
    };
  }, []);
  
  return <YourApp />;
}

就这么简单！现在您的应用程序将在开发模式下显示一个浮动的调试面板，让您可以访问所有调试功能。

内置功能

通过上面的一行代码初始化，您将自动获得以下所有调试功能：

• 网络监控：跟踪和检查所有网络请求和响应
• 控制台日志：在应用内查看所有控制台日志输出
• Zustand状态：监控Zustand状态管理（如果您的应用使用Zustand）
• 导航跟踪：自动记录应用内的导航事件
• 第三方调试工具：快速访问原生调试工具（iOS的FLEX，iOS和Android的DoraemonKit）

集成

高级Axios网络跟踪

对于使用Axios的项目，您可以启用更详细的网络请求跟踪：

import axios from 'axios';
import { createNetworkFeature, isDebugMode } from 'react-native-debug-toolkit';

// 获取网络功能实例并设置Axios拦截器
if (isDebugMode) {
  const networkFeature = createNetworkFeature();
  networkFeature.setupAxiosInterceptors(axios);
  
  // 可选：排除敏感URL（如认证接口）
  networkFeature.addUrlToBlacklist('api.example.com/auth');
  networkFeature.addUrlToBlacklist(/password/i); // 支持正则表达式
}

监控Zustand状态（如果您使用Zustand）

如果您的应用使用Zustand进行状态管理，只需添加中间件即可跟踪所有状态变化：

import { create } from 'zustand';
import { zustandLogMiddleware } from 'react-native-debug-toolkit';

// 只需添加zustandLogMiddleware来包装您的store
const useStore = create(
  zustandLogMiddleware(
    (set) => ({
      count: 0,
      increment: () => set((state) => ({ count: state.count + 1 })),
      decrement: () => set((state) => ({ count: state.count - 1 })),
    })
  )
);

导航跟踪（React Navigation）

如果您使用React Navigation，添加导航跟踪只需一步：

import React, { useRef } from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { useNavigationLogger } from 'react-native-debug-toolkit';

function AppNavigator() {
  const navigationRef = useRef(null);
  
  // 添加这一行来启用导航日志
  useNavigationLogger(navigationRef);
  
  return (
    <NavigationContainer ref={navigationRef}>
      {/* 您的导航配置 */}
    </NavigationContainer>
  );
}

自定义配置

如果您不需要所有功能，可以选择性地启用特定功能：

// 只启用网络和控制台日志功能
initializeDebugToolkit(['network', 'console']);

// 或者指定一组自定义功能
initializeDebugToolkit([
  'network',
  'console', 
  'zustand', 
  'navigation',
  'thirdPartyLibs'
]);

常见问题排除

调试面板不显示

• 确保您在开发模式下（isDebugMode为true）
• 检查是否正确调用了initializeDebugToolkit()

iOS功能不工作

• 确认您已将FLEX和DoraemonKit添加到Podfile
• 在修改后重新运行pod install
• 确保您正在运行Debug构建版本

网络请求未被捕获

• 对于Axios，请确保调用了setupAxiosInterceptors(axios)
• 对于fetch请求，工具包会自动拦截，无需额外配置

应用性能问题

• 此调试工具包仅适用于开发阶段，请确保生产构建中未包含
• 如果开发模式下性能受影响，可以尝试只启用特定功能