常见问题解决

本指南收集了开发过程中最常见的问题及其详细解决方案，帮助您快速排除故障，提高开发效率。

🎯 问题分类

问题按以下类别整理：

• 🔧 环境配置问题 - 系统、工具安装相关
• 📦 编译构建问题 - 代码编译、打包相关
• 📱 设备连接问题 - ADB、设备通信相关
• 🌐 网络相关问题 - 下载、连接、代理相关
• 🚀 部署运行问题 - 应用安装、运行相关

🔧 环境配置问题

WSL 相关问题

问题1：WSL 安装失败或无法启动

# 症状：安装 WSL 时出错或无法启动

解决方案：

# 1. 检查 Windows 版本
winver  # 确保是 Windows 10 2004+ 或 Windows 11

# 2. 启用虚拟化功能
# 进入 BIOS，启用 Virtualization Technology

# 3. 重新启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 4. 重启计算机后重试
wsl --install -d Ubuntu-22.04

问题2：WSL2 中无法访问 Windows 文件

# 症状：在 WSL2 中无法看到 Windows 文件系统

解决方案：

# Windows 文件系统挂载在 /mnt/ 下
ls -la /mnt/c/Users/

# 如果看不到，手动挂载
sudo mkdir -p /mnt/c
sudo mount -t drvfs C: /mnt/c

# 永久挂载，编辑 /etc/fstab
echo "C: /mnt/c drvfs defaults 0 0" | sudo tee -a /etc/fstab

Ubuntu 系统问题

问题3：apt update 失败

# 症状：E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?

解决方案：

# 1. 检查网络连接
ping -c 4 8.8.8.8

# 2. 重置 APT 缓存
sudo rm -rf /var/lib/apt/lists/*
sudo apt clean
sudo apt update

# 3. 修复损坏的包
sudo apt --fix-broken install

# 4. 换用国内镜像源
sudo cp /etc/apt/sources.list /etc/apt/sources.list.backup
sudo sed -i 's/http:\/\/archive.ubuntu.com/https:\/\/mirrors.aliyun.com/g' /etc/apt/sources.list
sudo apt update

问题4：磁盘空间不足

# 症状：No space left on device

解决方案：

# 1. 检查磁盘使用情况
df -h
du -sh /* 2>/dev/null | sort -hr | head -10

# 2. 清理系统缓存
sudo apt clean
sudo apt autoremove
sudo apt autoclean

# 3. 清理日志文件
sudo journalctl --disk-usage
sudo journalctl --vacuum-time=3d

# 4. 清理临时文件
sudo rm -rf /tmp/*
sudo rm -rf /var/tmp/*

# 5. 清理包缓存
sudo rm -rf /var/cache/apt/archives/*.deb

📦 编译构建问题

NodeJS/npm 问题

问题5：npm install 失败

# 症状：npm ERR! network timeout / EACCES / ENOTFOUND

解决方案：

# 1. 清理 npm 缓存
npm cache clean --force
rm -rf node_modules package-lock.json

# 2. 换用国内镜像源
npm config set registry https://registry.npmmirror.com

# 3. 增加超时时间
npm config set timeout 300000

# 4. 解决权限问题
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# 5. 使用 yarn 或 pnpm 替代
npm install -g pnpm
pnpm install

问题6：Node.js 版本不兼容

# 症状：engine "node" is incompatible

解决方案：

# 1. 安装 NVM 管理多版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# 2. 安装和切换 Node.js 版本
nvm install 18
nvm use 18
nvm alias default 18

# 3. 验证版本
node --version
npm --version

CMake 编译问题

问题7：CMake 找不到编译器

# 症状：CMake Error: CMAKE_CXX_COMPILER not set

解决方案：

# 1. 安装编译工具
sudo apt install build-essential cmake

# 2. 检查编译器路径
which gcc
which g++

# 3. 手动指定编译器
export CC=/usr/bin/gcc
export CXX=/usr/bin/g++

# 4. 清理 CMake 缓存重新配置
rm -rf jsapi/build
mkdir -p jsapi/build
cd jsapi/build
cmake ..

问题8：交叉编译工具链找不到

# 症状：Could not find ARM toolchain

解决方案：

# 1. 检查工具链目录
ls -la jsapi/toolchains/

# 2. 验证工具链可执行性
file jsapi/toolchains/armv7-eabihf--glibc--stable-2018.11-1/bin/arm-buildroot-linux-gnueabihf-gcc
chmod +x jsapi/toolchains/armv7-eabihf--glibc--stable-2018.11-1/bin/*

# 3. 检查工具链配置
cat jsapi/toolchain.cmake

# 4. 手动设置工具链路径
export PATH="$PWD/jsapi/toolchains/armv7-eabihf--glibc--stable-2018.11-1/bin:$PATH"

问题9：链接库找不到

# 症状：cannot find -lcurl, -lsqlite3

解决方案：

# 1. 检查库文件是否存在
ls -la jsapi/lib/
file jsapi/lib/libcurl.so
file jsapi/lib/libsqlite3.so

# 2. 检查版本信息是否正确提取
tar -tf versionInfo.tar.gz | grep -E "(lib|include)"

# 3. 重新提取版本信息
rm -rf jsapi/include jsapi/lib
tar -xzf versionInfo.tar.gz -C ./jsapi

# 4. 检查 CMake 库路径配置
grep -r "lib" jsapi/CMakeLists.txt

📱 设备连接问题

ADB 连接问题

问题10：adb devices 显示 unauthorized

# 症状：List of devices attached
#       ABC123DEF456    unauthorized

解决方案：

# 1. 重启 ADB 服务
adb kill-server
adb start-server

# 2. 在设备上重新授权
# 设备会弹出授权对话框，点击"总是允许"

# 3. 删除旧的授权密钥
rm ~/.android/adbkey*
adb kill-server
adb start-server

# 4. 检查 RSA 密钥
ls -la ~/.android/

问题11：设备连接不稳定

# 症状：设备时连时断，adb 命令经常失败

解决方案：

# 1. 检查 USB 线和端口
# 更换 USB 数据线，尝试不同的 USB 端口

# 2. 检查设备电源管理
# 在设备上禁用 USB 选择性暂停

# 3. 增加 ADB 超时时间
export ADB_CONNECT_TIMEOUT_MS=10000

# 4. 使用网络 ADB
adb tcpip 5555
adb connect device_ip:5555

# 5. 监控连接状态
watch -n 1 'adb devices'

问题12：Linux 下 USB 权限问题

# 症状：no permissions (user in plugdev group)

解决方案：

# 1. 创建 udev 规则
sudo tee /etc/udev/rules.d/51-android.rules << 'EOF'
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor}=="1004", MODE="0666", GROUP="plugdev"
EOF

# 2. 重新加载 udev 规则
sudo udevadm control --reload-rules
sudo udevadm trigger

# 3. 添加用户到 plugdev 组
sudo usermod -a -G plugdev $USER

# 4. 重新登录或运行
newgrp plugdev

# 5. 重启 ADB
adb kill-server
adb start-server

🌐 网络相关问题

下载问题

问题13：下载速度慢或超时

# 症状：wget/curl 下载很慢或超时

解决方案：

# 1. 使用国内镜像源
# 参考 [网络问题和换源指南](Network-Issues-and-Mirror-Setup)

# 2. 使用多线程下载
sudo apt install aria2
aria2c -x 10 -s 10 https://example.com/file.tar.gz

# 3. 配置代理（如果有）
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

# 4. 增加重试和超时设置
wget --tries=5 --timeout=30 --waitretry=10 url

问题14：SSL 证书验证失败

# 症状：SSL certificate problem: unable to get local issuer certificate

解决方案：

# 1. 更新 CA 证书
sudo apt update
sudo apt install ca-certificates

# 2. 更新证书存储
sudo update-ca-certificates

# 3. 临时跳过验证（不推荐）
curl -k https://example.com
wget --no-check-certificate https://example.com

# 4. 检查系统时间
date
sudo ntpdate -s time.nist.gov  # 如果时间不对

代理相关问题

问题15：代理配置不生效

# 症状：设置了代理但仍无法访问外网

解决方案：

# 1. 检查代理设置
env | grep -i proxy

# 2. 测试代理连接
curl --proxy http://127.0.0.1:7890 -I https://www.google.com

# 3. 为不同工具单独设置代理
git config --global http.proxy http://127.0.0.1:7890
npm config set proxy http://127.0.0.1:7890

# 4. 检查代理服务是否运行
netstat -tulpn | grep 7890

# 5. 配置绕过代理的地址
export no_proxy="localhost,127.0.0.1,.local"

🚀 部署运行问题

应用安装问题

问题16：miniapp_cli 命令不存在

# 症状：miniapp_cli: command not found

解决方案：

# 1. 检查设备是否支持 miniapp
adb shell which miniapp_cli

# 2. 查找 miniapp_cli 位置
adb shell find /system -name "*miniapp*" 2>/dev/null

# 3. 添加到 PATH
adb shell "export PATH=/system/bin:$PATH"

# 4. 检查设备系统版本
adb shell getprop ro.build.version.release

# 5. 确认设备型号是否支持
adb shell getprop ro.product.model

问题17：应用安装失败

# 症状：installation failed: INSTALL_FAILED_INSUFFICIENT_STORAGE

解决方案：

# 1. 检查设备存储空间
adb shell df -h

# 2. 清理设备存储
adb shell rm -rf /userdisk/cache/*
adb shell rm -rf /tmp/*

# 3. 检查应用包大小
ls -lh dist/miniapp.amr

# 4. 检查安装路径权限
adb shell ls -la /userdisk/Favorite/

# 5. 尝试不同的安装路径
adb push dist/miniapp.amr /sdcard/
adb shell miniapp_cli install /sdcard/miniapp.amr

运行时问题

问题18：应用启动后崩溃

# 症状：应用安装成功但启动后立即退出

解决方案：

# 1. 查看崩溃日志
adb logcat -c
adb shell miniapp_cli launch com.miniapp.package
adb logcat -d | grep -E "(FATAL|ERROR|CRASH)"

# 2. 检查依赖库
adb shell ldd /path/to/miniapp/binary

# 3. 检查权限配置
adb shell ls -la /userdisk/miniapp/

# 4. 验证应用签名
adb shell dumpsys package com.miniapp.package | grep signature

# 5. 重新安装应用
adb shell miniapp_cli uninstall com.miniapp.package
adb shell miniapp_cli install /userdisk/Favorite/miniapp.amr

问题19：功能异常或无响应

# 症状：应用能启动但某些功能不工作

解决方案：

# 1. 检查网络连接
adb shell ping -c 3 8.8.8.8

# 2. 查看应用日志
adb logcat -s "MiniApp:*" | head -50

# 3. 检查数据库文件
adb shell ls -la /userdisk/miniapp/*.db

# 4. 验证配置文件
adb shell cat /userdisk/miniapp/config.json

# 5. 重置应用数据
adb shell rm -rf /userdisk/miniapp/cache/
adb shell miniapp_cli restart com.miniapp.package

🔍 问题诊断工具

自动诊断脚本

创建 diagnose.sh 脚本：

#!/bin/bash
# 自动诊断脚本

echo "🔍 开始系统诊断..."

# 检查基本环境
echo "📋 环境检查..."
echo "系统: $(lsb_release -d | cut -d: -f2 | xargs)"
echo "内核: $(uname -r)"
echo "磁盘: $(df -h / | tail -1 | awk '{print $4}') 可用"

# 检查必需工具
echo "🛠️ 工具检查..."
tools=("git" "cmake" "gcc" "node" "npm" "pnpm" "adb")
for tool in "${tools[@]}"; do
    if command -v $tool &> /dev/null; then
        echo "✅ $tool: $(which $tool)"
    else
        echo "❌ $tool: 未安装"
    fi
done

# 检查网络连接
echo "🌐 网络检查..."
if ping -c 1 8.8.8.8 &> /dev/null; then
    echo "✅ 网络连接正常"
else
    echo "❌ 网络连接异常"
fi

# 检查设备连接
echo "📱 设备检查..."
device_count=$(adb devices | grep -c "device$")
if [ $device_count -gt 0 ]; then
    echo "✅ 发现 $device_count 个设备"
    adb devices
else
    echo "❌ 没有发现设备"
fi

# 检查项目结构
echo "📁 项目检查..."
if [ -f "package.json" ] || [ -f "CMakeLists.txt" ]; then
    echo "✅ 项目结构正常"
else
    echo "❌ 项目结构异常"
fi

echo "✅ 诊断完成"

日志收集脚本

创建 collect_logs.sh 脚本：

#!/bin/bash
# 日志收集脚本

LOG_DIR="logs_$(date +%Y%m%d_%H%M%S)"
mkdir -p $LOG_DIR

echo "📊 收集系统信息..."

# 系统信息
{
    echo "=== 系统信息 ==="
    lsb_release -a
    uname -a
    free -h
    df -h
} > $LOG_DIR/system_info.txt

# 环境变量
env > $LOG_DIR/environment.txt

# 网络配置
{
    echo "=== 网络配置 ==="
    cat /etc/resolv.conf
    echo "=== 路由表 ==="
    ip route
} > $LOG_DIR/network_config.txt

# 已安装包
dpkg -l > $LOG_DIR/installed_packages.txt

# Git 配置
git config --list > $LOG_DIR/git_config.txt

# npm 配置
npm config list > $LOG_DIR/npm_config.txt

# ADB 设备
adb devices > $LOG_DIR/adb_devices.txt

# 设备日志（如果有连接的设备）
if adb devices | grep -q "device$"; then
    adb logcat -d > $LOG_DIR/device_logcat.txt 2>/dev/null
fi

echo "✅ 日志已收集到 $LOG_DIR/"
tar -czf ${LOG_DIR}.tar.gz $LOG_DIR/
echo "📦 日志包: ${LOG_DIR}.tar.gz"

📞 获取帮助

在线资源

• 项目 GitHub Issues: https://github.com/langningchen/miniapp/issues
• 有道词典笔开发者社区: PenUniverse Discussions
• Ubuntu 社区帮助: https://help.ubuntu.com/
• Node.js 官方文档: https://nodejs.org/docs/
• CMake 文档: https://cmake.org/documentation/

提交问题时的信息

请包含以下信息：

• 操作系统版本
• 使用的工具版本
• 完整的错误信息
• 重现问题的步骤
• 已尝试的解决方案

社区交流

• 在提问前请先搜索已有问题
• 描述问题时尽量详细
• 提供可重现的测试用例
• 感谢帮助您的社区成员

---

还有其他问题？ 请在 GitHub Issues 中提出，我们会尽快回复。