audio_codebuddy/docs/app-troubleshooting.md

App 端问题排查记录

marked 包 Unicode 正则导致 App 白屏

日期: 2026-05-05

问题现象

• App 端白屏，无法正常显示
• H5 和小程序正常，只有 App 有问题

• 控制台报错:

  Invalid regular expression: /[\p{L}\p{N}]/: Invalid property name in character class
  

根本原因

marked 包 v10+ 使用了 Unicode 属性转义正则表达式（如 /\p{L}\p{N}/u），App 基座的旧版 JS 引擎不支持。

解决方案

降级 marked 到旧版本：

npm install marked@4.3.0 --legacy-peer-deps

预防措施

1. 第三方包升级前先在 App 基座测试
2. 避免使用太新的 npm 包（特别是涉及正则表达式的）
3. 定期测试 App 端构建

---

uni-app 运行环境版本和编译器版本不一致

日期: 2026-05-05

问题现象

App 启动时提示：

本应用使用HBuilderX4.84或对应的cli版本编译，而手机端SDK版本是5.07

根本原因

cli 项目的编译器版本与 HBuilderX 版本不同步，需要手动升级编译器。

解决方案

npm install @dcloudio/uni-app@latest --legacy-peer-deps
# 或指定版本
npm install @dcloudio/uni-app@3.0.0-alpha-5000720260416001 --legacy-peer-deps

升级后验证：

npm list @dcloudio/uni-app

预防措施

1. 定期执行 npm update @dcloudio/uni-app 保持编译器最新
2. 升级 HBuilderX 后记得同步升级 cli 编译器

---

Android 手机网络请求无反应

日期: 2026-05-05

问题现象

App 没有任何网络请求，接口没调用。

根本原因

1. config.ts 中 getPlatform() 获取的平台名为首字母大写（如 Android），而配置对象用的是小写（android）
2. 导致 API 地址为 undefined

解决方案

修复 config.ts 中的平台判断：

function getPlatform(): 'web' | 'android' | 'ios' | 'h5' {
  // #ifdef APP-PLUS
  const systemInfo = uni.getSystemInfoSync();
  const platform = (systemInfo.platform || '').toLowerCase();
  if (platform === 'android') return 'android';
  if (platform === 'ios') return 'ios';
  return 'android';
  // #endif
  return 'web';
}

相关文件

• my-uniapp-vue3/src/utils/config.ts

---

App 端 window/document/localStorage 兼容性问题

日期: 2026-05-05

已修复的文件

1. player/index.vue - window.location.href 和 window.location.origin

   • 使用条件编译处理：// #ifdef H5 / // #ifndef H5

2. book-generator/index.vue - new URL(), window.location.hash, history.pushState

   • 使用条件编译处理

3. payment-confirm/index.vue - window.location.origin

   • 使用条件编译处理

4. NetworkStatus.vue - window.addEventListener

   • App 端改用 uni.onNetworkStatusChange API

5. request.ts - require() 动态导入

   • 改为 ES6 import 静态导入

需要注意的 API（H5专用，App不支持）

API	H5	App	替代方案
window.location	✅	❌	条件编译
document.createElement	✅	❌	条件编译
localStorage	✅	❌	uni.getStorageSync
navigator.share	✅	❌	uni.share
history.pushState	✅	❌	条件编译
new URL()	✅	❌	条件编译

建议

所有使用 H5 特有 API 的地方，都应该使用条件编译：

// #ifdef H5
// H5 专用代码
// #endif

// #ifndef H5
// App/小程序 专用代码
// #endif

---

JSON.stringify 循环引用导致 App 崩溃

日期: 2026-05-05

问题现象

App 页面报错：TypeError: Converting circular structure to JSON

根本原因

getCurrentPages() 返回的页面对象包含循环引用（$vm 属性），不能直接用 JSON.stringify() 序列化。

解决方案

避免对页面对象使用 JSON.stringify：

// 错误 ❌
const pages = getCurrentPages();
const currentPage = pages[pages.length - 1];
console.log(JSON.stringify(currentPage)); // 会崩溃！

// 正确 ✅
const pages = getCurrentPages();
const currentPage = pages[pages.length - 1] as any;
const id = currentPage?.options?.id; // 直接访问属性

已修复的文件

• player/index.vue - 移除 JSON.stringify(currentPage)

---

CSS gap 属性在 App 端不兼容

日期: 2026-05-05

问题现象

播放器页面在 App 上布局错乱，很多元素重叠或位置不对。

根本原因

App 基座不支持 CSS gap 属性。

解决方案

使用 margin 替代 gap：

/* 错误 ❌ */
.container {
  display: flex;
  gap: 16rpx;
}

/* 正确 ✅ */
.container {
  display: flex;
}
.container > view {
  margin-right: 16rpx;
}

已修复的文件

• player/index.vue - 所有 gap 改用 margin

预防措施

开发时使用 H5 测试，但发布前务必在 App 真机上测试布局。