@ssv-labAnim 调试工具插件
一个为小程序开发提供调试工具的 Anim 插件，支持环境配置切换、请求拦截、自定义请求头、VConsole 调试等功能。
功能特性
- 环境切换: 支持前端/后端配置环境快速切换
- 请求拦截: 自动拦截和修改网络请求
- 自定义请求头: 灵活配置 HTTP 请求头
- VConsole 集成: 一键开启/关闭调试控制台
- 请求日志: 详细的网络请求日志记录
- 快捷访问: 通过多次点击快速进入调试页面
安装
bash
npm install @ssv-lab/anim-plugin-devtool --save
基础用法
1. 注册插件
js
// app.js
import Anim from '@ssv-lab/anim';
import DevtoolPlugin from '@ssv-lab/anim-plugin-devtool';
const configMap = {
develop: {
title: '开发环境',
BASE_URL: 'https://dev-api.example.com',
FILE_URL: 'https://test-cos.example.com',
},
trial: {
title: '测试环境',
BASE_URL: 'https://test-api.example.com',
FILE_URL: 'https://test-cos.example.com',
},
release: {
title: '生产环境',
BASE_URL: 'https://api.example.com',
FILE_URL: 'https://prod-cos.example.com',
}
}
const {
miniProgram: { envVersion },
version,
} = wx.getAccountInfoSync() || {};
const config = {
...configMap[envVersion],
version,
// 其他配置
}
Anim.use(DevtoolPlugin, {
configMap,
env: envVersion,// 默认前端环境， 可不传，不传会自动获取当前小程序的版本信息
homePath: '', // 确定后重启小程序默认跳转首页，可不传，不传为devtool路径
apiInterceptors: { // 请求拦截默认关闭,开启请求
enable: false,
apiKeys: ['BASE_URL']
}
});
App({
onLaunch() {
console.log('App launched');
}
});
2. 初始化调试页面
运行命令生成调试页面：
bash
npx anim-plugin-devtool init
此命令会：
- 创建 dev-tool/page/ 目录结构
- 生成调试页面文件 (index.js, index.json, index.wxml, index.wxss)
- 自动配置 app.json 的 subpackages
3. 添加快捷入口
在需要调试的页面中添加快捷访问：
js
// pages/index/index.js
import { handleClickByDevTool } from '@ssv-lab/anim-plugin-devtool';
Page({
data: {
title: 'Hello World'
},
// 绑定到某个元素的点击事件
onTitleTap() {
handleClickByDevTool(); // 连续点击5次进入调试页面
}
});
xml
<!-- pages/index/index.wxml -->
<view>
<text bind:tap="onTitleTap">{{title}}</text>
</view>
配置选项
configMap【必填】
环境配置映射，定义不同环境的 API 地址， 内容可完全自定义：
js
{
configMap: {
[环境标识]: {
title: '环境名称', // 显示名称
BASE_URL: 'API地址' // 后端API地址
}
}
}
env【非必填】
指定默认的前端环境标识，对应 configMap 中的 key。
homePath【非必填】
确定后重启小程序默认跳转首页，可不传，不传为devtool路径。
apiInterceptors【非必填】
js
{
apiInterceptors: {
enable: false, // 默认不开启
apiKeys: ['BASE_URL'] // 代理的api，key
}
}
是否开启请求拦截器，默认为false，开启后支持用户输入自定义请求api以及请求头
调试页面功能
调试页面提供以下功能模块：
1. 前端环境显示
显示当前小程序的前端环境信息。
2. 后端环境切换
- 支持在不同后端环境间切换
- 切换环境会自动清空登录信息
- 支持自定义环境配置
3. 自定义请求头
json
{
"Authorization": "Bearer your-token",
"Custom-Header": "custom-value",
"BASE_URL": "https://custom-api.example.com"
}
4. VConsole 调试
一键开启/关闭 VConsole 调试工具。
API 说明
handleClickByDevTool(path)
快捷访问调试页面的函数。
- 参数:
- path (string, 可选): 调试页面路径，默认为 /dev-tool/page/index
- 用法: 连续点击5次（2秒内）触发跳转
devToolPlugin 实例方法
js
import devToolPlugin from '@ssv-lab/anim-plugin-devtool';
// 设置自定义请求头
devToolPlugin.setHeaders({
'Authorization': 'Bearer token',
'BASE_URL': 'https://custom-api.com'
});
// 切换后端环境
devToolPlugin.changeEnv('trial');
// 跳转调试页面
devToolPlugin.goDevToolPage('/dev-tool/page/index');
// 获取当前后端环境名称
const envName = devToolPlugin.getBackendEnvName();
请求拦截机制
插件会自动拦截所有网络请求并：
- URL 替换: 根据当前后端环境替换请求 URL
- 请求头注入: 自动添加自定义请求头
- 请求日志: 记录详细的请求和响应信息
注意事项
- 生产环境: 插件在生产环境（release）下会自动禁用
- 存储清理: 切换环境会清空部分本地存储，但保留调试工具相关配置
- 请求格式: 自定义请求头必须是有效的 JSON 格式
- 快捷访问: 需要在2秒内连续点击5次才能触发调试页面跳转
常见问题
Q: 为什么调试页面无法访问？
A: 确保已运行 npx anim-plugin-devtool init 命令生成调试页面。
Q: 环境切换后请求还是指向原环境？
A: 检查 configMap 配置是否正确，确保 BASE_URL 格式正确。
Q: 自定义请求头不生效？
A: 确保 JSON 格式正确，检查调试页面是否有错误提示。