MiniDebug

MiniDebug是一款旨在提高多端小程序开发、测试效率的工具库。

特性

基于Taro框架开发，支持多端。
基于Taro UI组件库实现，界面美观。
功能丰富，满足多样化开发、调试需求。
本身是组件，引入简单，代码侵入性小。

架构图

1. MiniDebug架构图

miniDebug工具基于Taro框架开发，可编译成多端小程序应用。利用原生能力支持，通过暴露API，以及修改全局state、storage数据实现和业务层的数据交互。

2. 宿主工程引入MiniDebug架构图

宿主工程通过npm引入miniDebug工具，通过判断环境ENV，在编译阶段实现miniDebug承载页的动态注册。

功能介绍

主要功能包括环境切换、身份Mock、应用信息获取、位置模拟、缓存管理、扫一扫、H5跳转、更新版本等。工具首页如图所示。

1. 环境切换

让小程序在测试、预发、正式环境中随意切换。支持热加载，无需手动重启应用。

2. 身份Mock

动态切换登录账号（仅支持测试环境，预发、正式环境不建议明文传输用户身份）。

3. 应用信息获取

一键查看系统、账号、用户、授权信息，快速定位测试、UAT问题。

4. 位置模拟

功能包括

快速授权，小程序授权入口很深，该功能可一键快速进行权限授权。
查看位置，在地图上快速确定自己的位置。
选择位置，代理小程序getLocation方法，无需修改代码即可任意切换当前位置。
还原，一键还原用户位置。
地址转换，支持wgs84和gcj02坐标系互转。

5. 缓存管理

支持storage信息的查看、新增、删除、修改。

6. 扫一扫

主要用于扫描小程序码、二维码场景。微信原生扫一扫扫码会直接跳转线上版本，该功能可以跳转至相应开发、体验版本，提高测试效率，降低上线风险。

7. H5跳转

主要用于在App环境打开H5场景。如测试H5在微信环境某些特殊逻辑。

8. 更新版本

更新小程序版本。

快速上手

miniDebug工具基于Taro框架和Taro UI组件库开发，下面详细介绍引入步骤。

安装npm包

如果您的taro版本为1.x、2.x，请按如下方式安装

npm install @jdlfe/minidebug --save-dev

如果您的taro版本为3.x，请按如下方式安装

npm install @jdlfe/minidebug-next --save-dev

新建空页面

推荐在空目录下创建页面，该页面用于引入miniDebug组件

动态注册miniDebug承载页

taro1.x、2.x版本：修改App下的config对象里的pages属性，利用Taro的preval。如下所示，判断process.env.NODE_ENV，在非生产环境时才将miniDebug承载页注册，保证生产环境打包不包含miniDebug内容。

class App extends Taro.Component {
  config = {
    pages: preval`
      module.exports=(function() {
        const path = [
          'pages/module/pageA',
          'pages/module/pageB',
          'pages/module/pageC'
        ]
        if (process.env.NODE_ENV !== 'production') {
          path.push('packageD/debug/index') 
        }
        return path
      })()
    `,

taro3.x版本：在app.config.ts中注册miniDebug承载页

// 获取页面路径
const getPages = () => {
  const path = [
    'pages/module/pageA',
    'pages/module/pageB',
    'pages/module/pageC'
  ]
  // 非生产环境注册debug承载页
  if (process.env.NODE_ENV !== 'production') {
    path.push('packageD/debug/index')
  }
  return path
}
export default {
  pages: getPages(),
  window: {
    backgroundTextStyle: 'light',
    navigationBarBackgroundColor: '#fff',
    navigationBarTitleText: 'WeChat',
    navigationBarTextStyle: 'black'
  }
}

引入miniDebug组件

只需将miniDebug作为普通Taro组件引入。taro1.x、2.x版本：

import { Debug } from '@jdlfe/minidebug'

taro 3.x版本：

import { Debug } from '@jdlfe/minidebug-next'

引入组件依赖的样式文件。taro1.x、2.x版本：

@import '~@jdlfe/minidebug/src/app.scss'

taro 3.x版本：

@import "~@jdlfe/minidebug-next/dist/style/index.scss";

修改render函数

render() {
  return (
    <View className="debug-container">
      {/* 将miniDebug当做普通组件引入 */}
      <Debug />
    </View>
  )
}

首页新增miniDebug入口

该方法需在render函数中调用

renderDebug() {
  // 只有测试、预发环境，才会展示miniDebug入口
  if (process.env.NODE_ENV === 'production') return false
  return (
    <View className="debug" onClick={this.goMinDebug}>
      debug
    </View>
  )
}

跳转miniDebug方法

goMiniDebug() {
  Taro.navigateTo({
    url: `/packageD/debug/index`
  })
}

切换环境功能引入

因不同项目测试、预发、正式环境变量不同，因此，通过miniDebug切换完环境后，首先会将设置的环境变量保存到storage中，然后会暴露一个全局状态，在应用首页检测到该状态值时，需要您自行实现环境变量切换的方法。

// 此段代码通常在小程序入口文件，onLoad第一行
// Taro.getApp().needResetHttp为true，代表用户通过miniDebug修改了环境变量
if (Taro.getApp().needResetHttp) {
  // 将标识重置
  Taro.getApp().needResetHttp = false
  // resetHttp即为更改环境变量的方法，需要自行实现
  resetHttp()
}
// 参考实现
const ROOT_PATH = {
  development: 'https://test.test.com',
  prepare: 'https://uat.test.com',
  production: 'https://prod.test.com',
}
resetHttp() {
  try {
    // 先获取miniDebug中修改的env环境变量，有效取值为"development"、"prepare"、"production"
    const env = Taro.getStorageSync('env') || "production"
    // 根据miniDebug设置的env，更改网络请求URL
    // 你的项目可能识别的设置方式，目的是更改网络请求的base URL
    Taro.getApp().globalData.Http.config.root = ROOT_PATH[env]
  } catch (e) {}
}

F&Q

1. taro1.x版本，构建后提示“Error: File to import not found or unreadable: ~@jdlfe/minidebug/src/app.scss.”

原因是找不到minidebug的样式文件，需要在config/index配置文件新增sass配置，参考配置如下：

const path = require('path')
const sassImporter = function(url) {
  if (url[0] === '~' && url[1] !== '/' && (url.includes('minidebug') || url.includes('taro-ui'))) {
    return {
      file: path.resolve(__dirname, '..', 'node_modules', url.substr(1))
    }
  }
}
const config = {
  // ...
  sass: {
    importer: sassImporter,
  }
}

jdlfe / minidebug Goto Github PK

minidebug's Introduction