微信真机调试报错：wx is not defined

Question

在进行微信小程序真机调试时，开发者常遇到“wx is not defined”错误。该问题多出现在非微信环境中运行代码，如浏览器调试或H5页面直接引用小程序SDK。由于`wx`对象是微信客户端提供的全局变量，在非微信环境自然未定义。常见诱因包括误将小程序代码直接运行于浏览器、构建工具配置不当导致注入时机错误，或使用了不兼容的第三方库模拟`wx` API。解决方法为确保代码仅在微信客户端执行，并通过条件判断防止`wx`未定义报错，例如添加`typeof wx !== 'undefined'`校验。

Answer 1

一、问题背景与常见现象

在进行微信小程序真机调试时，开发者常遇到“wx is not defined”错误。该问题多出现在非微信环境中运行代码，如浏览器调试或H5页面直接引用小程序SDK。

wx对象是微信客户端提供的全局变量，封装了所有小程序原生API（如网络请求、本地存储、设备信息等），其本质由微信JSBridge注入，在WebView加载时初始化。

当开发者尝试将小程序逻辑层代码（如app.js、page.js）直接运行于浏览器环境（例如通过Webpack Dev Server预览）时，由于缺少微信运行时上下文，导致wx未被定义，从而抛出ReferenceError。

二、根本原因分析

• 误将小程序代码运行于浏览器环境：部分团队采用H5+小程序双端复用架构，若未做好环境隔离，可能导致wx调用泄露至Web端。
• 构建工具配置不当：如Webpack/Vite未正确识别平台目标，提前打包含wx调用的模块，且未做条件编译处理。
• 第三方库兼容性问题：某些UI库或工具库内部直接引用wx API（如wx.showModal），但在非微信环境未提供降级方案。
• 模拟器与真机差异：开发者工具中wx已被模拟注入，但真机调试时因网络、权限或版本问题未能及时加载JS-SDK。

三、诊断流程图

    graph TD
        A[出现 'wx is not defined'] --> B{执行环境是否为微信?}
        B -- 是 --> C[检查微信版本是否支持API]
        B -- 否 --> D[确认是否应在此环境运行]
        C --> E[检查SDK注入时机]
        D --> F[添加环境判断保护]
        E --> G[查看network面板是否有JS资源加载失败]
        F --> H[使用typeof校验wx存在性]
    

四、解决方案层级递进

层级	策略	适用场景	实现方式
L1 - 代码防护	条件判断wx是否存在	通用容错	if (typeof wx !== 'undefined') { wx.request({...}) }
L2 - 环境标识	定义全局环境变量IS_MINIPROGRAM	多端项目区分	Webpack DefinePlugin注入{ 'process.env.PLATFORM': '"miniprogram"' }
L3 - 构建隔离	按平台拆分入口文件	H5/小程序共用仓库	使用src/platforms/mp/与src/platforms/h5/目录分离
L4 - API抽象层	封装统一接口适配层	长期维护大型项目	创建api/request.js，内部根据环境选择wx.request或fetch
L5 - 模拟注入	开发阶段模拟wx对象	浏览器调试小程序逻辑	引入mock-wx库或自定义空函数桩

五、典型代码示例

以下为推荐的防御性编程写法：

// 安全调用 wx API
function safeWxCall(method, options) {
  if (typeof wx === 'undefined') {
    console.warn(`wx.${method} not available in current environment`);
    return Promise.reject(new Error('wx not defined'));
  }
  return new Promise((resolve, reject) => {
    wx[method]({ ...options, success: resolve, fail: reject });
  });
}

// 使用示例
safeWxCall('request', {
  url: 'https://api.example.com/data'
}).then(res => {
  console.log('Data:', res.data);
});
    

六、高级工程化建议

对于拥有5年以上经验的IT从业者，建议从架构层面规避此类问题：

1. 建立platform-adaptor层，统一抽象设备能力调用（如storage、network、location）。
2. 在CI/CD流程中加入环境检测脚本，防止误提交非兼容代码到主干分支。
3. 使用TypeScript定义wx类型声明，并结合@types/wechat-miniprogram提升开发体验。
4. 在Monorepo中通过packages/shared共享业务逻辑，但严格限制原生API调用仅出现在特定子包。
5. 利用Babel插件在编译期重写或移除特定平台API调用，实现真正的按需注入。
6. 监控线上错误日志系统，对wx is not defined类异常设置告警规则。
7. 推动团队制定《跨端开发规范》，明确禁止在基础工具函数中硬编码wx依赖。
8. 采用微前端或组件化设计，将小程序特有能力封装为独立可插拔模块。
9. 定期审计第三方依赖，避免引入隐式依赖微信环境的NPM包。
10. 在文档中维护“常见环境差异表”，帮助新人快速理解各平台边界。