Skip to content

Troubleshooting zh

Ra1nify edited this page Oct 31, 2026 · 1 revision

故障处理

按现象分类。每项给出判定方法与处理步骤。

实例启动失败

核心未安装

概览页核心状态显示 未安装。安装核心后重试。

账号被占用

弹窗提示互斥冲突。处理方式二选一:

方式 操作 影响
终止原实例 在实例页停止占用进程后重试 原实例的未保存内容丢失
强制接管 确认风险提示后继续 原进程被终止,锁被清除

项目被占用

同上。项目占用记录在 data/projects.json 的 RunningInstanceId。

端口占用

实例启动需要绑定本地端口。提示端口冲突时关闭冲突进程,或重启 Gravityless 重新分配。

材质不生效

现象:窗口无 Mica 效果,或背景为纯色。

依次检查:

  1. 外观页材质选项是否为 关闭;
  2. 系统是否开启「透明效果」:设置 → 个性化 → 颜色 → 透明效果;
  3. 系统版本是否满足材质要求,见 外观 的材质表;
  4. 注册表 HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize\EnableTransparency 是否为 1。

材质由 DWM 绘制。上述任一条不满足时,DWM 不输出背板。

现象:补丁改动后材质无变化。

utils.js 的版本戳与程序中的 MicaPatchVersion 不一致时才重新注入。改动补丁模板后需自增该常量。重启实例生效。

浮层模糊不可见

现象:菜单、对话框背景无模糊。

原因按顺序排查:

  1. 背景模糊滑条为 0;
  2. 弹窗透明度设为 0%(popupAlpha 为 1,底色不透明,遮蔽模糊);
  3. 浮层下方为空白材质区,无页面内容可采样。

backdrop-filter 只采样页面内容,不采样 DWM 材质。

界面仍显示英文

现象:Antigravity 界面部分文案为英文。

判定:该文案是否在 locales/zh-CN.json 的键中。

情况 处理
键存在但未生效 重启实例
键不存在 向字典追加条目,键为英文原文
键存在但为片段 页面将整句拆为多段,需按片段分别加条目

Antigravity 版本升级后新增的文案不会自动进入字典。

会话在其他实例不可见

现象:实例 A 中新建的会话,实例 B 看不到。

按实例的项目绑定数判定:

绑定项目数 行为 处理
1 整目录 Junction,双向共享 应即时可见。检查两实例是否绑定同一项目
≥2 单向快照 会话在实例 A 退出时回写项目;实例 B 需重启后重新挂载才可见

回写条件:会话的 workspace_uris 包含某个绑定项目的本地路径。不满足时会话保留在实例沙盒内。

账号残留锁

现象:账号显示「使用中」,但无对应运行中进程。

实例异常退出后锁未释放。

处理:号池页点击 强制解锁,或 全部强制解锁 清除全部残留锁。

图标未更新

Windows 缓存 exe 图标。替换图标后资源管理器仍显示旧图标时:

  1. 关闭应用;
  2. 删除 %LocalAppData%\IconCache.db;
  3. 任务管理器重启 explorer.exe。

托盘图标不走系统图标缓存。修改 Assets\tray.ico 后重启应用即可。

数据位置

排查时优先检查以下路径:

路径 内容
<安装目录>\data\instances.json 实例状态
<安装目录>\data\projects.json 项目状态
<安装目录>\data\accounts.json 账号锁状态
<安装目录>\core\resources\app\dist\utils.js 补丁产物与版本戳
<安装目录>\core\resources\app.asar.stock 原始包备份

详见 数据目录。

恢复手段

情况 处理
补丁损坏 删除 core\resources\app\,从 app.asar.stock 重新解包
核心损坏 概览页卸载核心后重新安装,data\ 保留
配置损坏 删除对应的 JSON 文件,重启后按默认值重建

JSON 文件解析失败时按默认值处理,不阻断启动。

Clone this wiki locally