bubbly存在neovim插件版、web版、ai聊天版三个互不兼容的独立实现；需通过which bubbly、nvim --version、package.json/init.lua、应用市场开发者信息等确认版本，避免混用导致失效。
刚装上Bubbly就发现状态栏不显示、角色创建后语音没反应、或者npm install卡在依赖下载——这些问题不是你操作错了，而是没绕开几个关键前提。Bubbly项目在Neovim、Web前端、AI聊天三个不同技术栈中都存在同名但完全独立的实现，混用配置或安装路径会导致80%以上的“插件失效”报错。
确认你用的是哪个Bubbly
第一步：打开终端，执行which bubbly或nvim --version，看输出里有没有LuaJIT字样；第二步：检查当前目录是否存在package.json或init.lua；第三步：手机端用户直接看App Store/华为应用市场下载页的“开发者”字段——【Neovim插件版由datwaft维护，Web版由siduck开发，AI聊天版由lovemo团队运营，三者代码库、配置方式、错误日志全不兼容】。
如果终端返回command not found且手机App内有“Moly钱包”图标，那你正在用AI聊天版，立刻退出Neovim去iOS设置里关掉“低数据模式”；如果nvim --version显示v0.9.5+但:PackerSync→等待完成→输入:qa!彻底退出→重新打开nvim。这一步能清掉packer缓存导致的模块加载中断，比单纯:source ~/.config/nvim/init.lua有效得多。
方法二：检查依赖插件是否真生效
运行:checkhealth bubbly，重点看gitsigns.nvim和nvim-lspconfig这两行是否标绿。如果标红，说明只是“已安装”，但没成功require——去你的plugins/目录下确认gitsigns.lua文件末尾有没有return require('gitsigns')这句，缺了就得手动补。
方法三：临时禁用主题干扰
在init.lua顶部加一行vim.o.background = 'dark'，保存后重启。很多主题（比如catppuccin）会覆盖bubbly的highlight组，导致文字透明化。这步做完再运行:BubblyToggle，如果状态栏突然弹出来，就证明是配色冲突。
AI聊天版blbbly角色语音不响的处理流程
第一步：点开右下角齿轮图标→进入「音频设置」→把「麦克风权限」和「扬声器测试」两个开关都拨到ON位置。
第二步：长按角色头像3秒→弹出菜单选「重置语音引擎」→等待进度条走完（约12秒）。
第三步：退出App→去手机系统设置→找到「blbbly」→清除全部缓存→重新打开App并登录。
【注意：安卓用户必须关闭MIUI的“智能省电”，否则后台语音服务会被强制冻结】
这一步做完，如果语音仍延迟超过5秒，说明当前网络DNS被污染，临时切到飞行模式再打开WiFi即可恢复。不用重装App，重装反而会丢失已训练的角色记忆。
Web版Bubbly npm install失败的应急方案
直接删掉整个项目文件夹，改用这个命令克隆：
git clone --depth 1 https://github.com/siduck/bubbly.git
然后进目录执行：
npm install --no-package-lock --legacy-peer-deps
最后启动：
npm start -- --port 3001
旧版本npm（--legacy-peer-deps跳过校验；--no-package-lock防止lock文件残留旧版本冲突；指定--port 3001避开本地8080端口被占用的情况——这三参数缺一不可。
