Repository navigation
Troubleshooting zh
按现象分类。每项给出判定方法与处理步骤。
核心未安装
概览页核心状态显示 未安装。安装核心后重试。
账号被占用
弹窗提示互斥冲突。处理方式二选一:
| 方式 | 操作 | 影响 |
|---|---|---|
| 终止原实例 | 在实例页停止占用进程后重试 | 原实例的未保存内容丢失 |
| 强制接管 | 确认风险提示后继续 | 原进程被终止,锁被清除 |
项目被占用
同上。项目占用记录在 data/projects.json 的 RunningInstanceId。
端口占用
实例启动需要绑定本地端口。提示端口冲突时关闭冲突进程,或重启 Gravityless 重新分配。
现象:窗口无 Mica 效果,或背景为纯色。
依次检查:
- 外观页材质选项是否为
关闭; - 系统是否开启「透明效果」:设置 → 个性化 → 颜色 → 透明效果;
- 系统版本是否满足材质要求,见 外观 的材质表;
- 注册表
HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize\EnableTransparency是否为1。
材质由 DWM 绘制。上述任一条不满足时,DWM 不输出背板。
现象:补丁改动后材质无变化。
utils.js 的版本戳与程序中的 MicaPatchVersion 不一致时才重新注入。改动补丁模板后需自增该常量。重启实例生效。
现象:菜单、对话框背景无模糊。
原因按顺序排查:
- 背景模糊滑条为 0;
- 弹窗透明度设为 0%(
popupAlpha为 1,底色不透明,遮蔽模糊); - 浮层下方为空白材质区,无页面内容可采样。
backdrop-filter 只采样页面内容,不采样 DWM 材质。
现象:Antigravity 界面部分文案为英文。
判定:该文案是否在 locales/zh-CN.json 的键中。
| 情况 | 处理 |
|---|---|
| 键存在但未生效 | 重启实例 |
| 键不存在 | 向字典追加条目,键为英文原文 |
| 键存在但为片段 | 页面将整句拆为多段,需按片段分别加条目 |
Antigravity 版本升级后新增的文案不会自动进入字典。
现象:实例 A 中新建的会话,实例 B 看不到。
按实例的项目绑定数判定:
| 绑定项目数 | 行为 | 处理 |
|---|---|---|
| 1 | 整目录 Junction,双向共享 | 应即时可见。检查两实例是否绑定同一项目 |
| ≥2 | 单向快照 | 会话在实例 A 退出时回写项目;实例 B 需重启后重新挂载才可见 |
回写条件:会话的 workspace_uris 包含某个绑定项目的本地路径。不满足时会话保留在实例沙盒内。
现象:账号显示「使用中」,但无对应运行中进程。
实例异常退出后锁未释放。
处理:号池页点击 强制解锁,或 全部强制解锁 清除全部残留锁。
Windows 缓存 exe 图标。替换图标后资源管理器仍显示旧图标时:
- 关闭应用;
- 删除
%LocalAppData%\IconCache.db; - 任务管理器重启
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 文件解析失败时按默认值处理,不阻断启动。
Gravityless · GPL-3.0 · English | 简体中文