在使用 Antigravity 1.15.8 版本时，部分用户遇到了无法启动 Chrome 浏览器的问题。虽然 1.14.x 版本工作正常，但升级到 1.15.8 后，浏览器自动化功能失效。本文记录该问题的根本原因及在 Windows 系统上的解决方案。

问题描述

尝试使用 Antigravity 1.15.8 的浏览器功能（如 browser_subagent、open_browser_url 等工具）时，浏览器无法启动。尚未搞清楚缘由，于是我重装了旧版本的 Antigravity 1.14.*，问题解决。

但是 2026-01-30 开始，提示旧版本不再支持，需要升级到最新版本。

1

This version of Antigravity is no longer supported. Please update to receive the latest features!

无奈之下，只能升级到 1.15.8 版本上，将问题解决再使用。经定位，问题的根本原因是 Windows 系统缺少 HOME 环境变量。

1
2

failed to create browser context: failed to install playwright: 
$HOME environment variable is not set

问题特征

  • 影响版本：Antigravity 1.15.8
  • 正常版本：Antigravity 1.14.x 系列
  • 故障现象：无法启动 Chrome 浏览器，Playwright 初始化失败
  • 错误根因：Windows 系统缺少 HOME 环境变量

根本原因分析

Antigravity 使用 Playwright 作为浏览器自动化引擎。从 1.15.8 版本开始，Playwright 的初始化逻辑对 HOME 环境变量产生了更严格的依赖：

  1. Playwright 安装机制：Playwright 需要在特定目录下安装浏览器二进制文件
  2. HOME 变量依赖：Playwright 使用 $HOME 环境变量来确定浏览器缓存和配置文件的存储位置
  3. Windows 系统差异：Windows 默认使用 USERPROFILE 而非 HOME 环境变量
  4. 版本变更影响：1.15.8 版本的 Playwright 集成方式改变，不再自动降级到 USERPROFILE

解决方案

Windows 系统操作步骤

在 Windows 系统上设置 HOME 环境变量的详细步骤：

方法一：通过系统属性设置（推荐）

  1. 打开系统属性
    • 右键点击”此电脑”（或”我的电脑”）
    • 选择”属性”
  2. 进入高级系统设置
    • 在系统窗口中，点击左侧的”高级系统设置”
    • 或在”关于”页面点击”高级系统设置”
  3. 打开环境变量配置
    • 在”系统属性”对话框中，点击”环境变量”按钮
  4. 新建用户环境变量
    • 在”用户变量”区域，点击”新建”按钮
    • 变量名：HOME
    • 变量值：你的用户文件夹路径，例如： 
      1
2
3

      C:\Users\Administrator
C:\Users\wanlin
C:\Users\<你的用户名>
  5. 应用设置
    • 点击”确定”保存环境变量
    • 依次确定关闭所有对话框
  6. 重启应用
    • 重要：关闭并重新启动 Antigravity
    • 环境变量更改仅对新启动的进程生效

方法二：通过命令行设置（临时）

打开 PowerShell 或命令提示符，执行以下命令：

1
2
3
4
5

# PowerShell
[System.Environment]::SetEnvironmentVariable('HOME', 'C:\Users\Administrator', 'User')

# 或使用 CMD
setx HOME "C:\Users\Administrator"

注意：使用 setx 命令设置的环境变量需要重启终端或应用才能生效。

方法三：验证环境变量设置

设置完成后，验证环境变量是否正确：

1
2
3
4
5

# PowerShell
echo $env:HOME

# 或使用 CMD
echo %HOME%

应该输出类似：

1

C:\Users\Administrator

获取当前用户路径的方法

如果不确定自己的用户文件夹路径，可以使用以下方法获取：

PowerShell：

1

$env:USERPROFILE

命令提示符：

echo %USERPROFILE%

文件资源管理器：

  • 地址栏输入 %USERPROFILE% 并回车
  • 复制地址栏显示的完整路径

验证修复效果

完成环境变量设置并重启 Antigravity 后，可以通过以下方式验证问题是否解决：

  1. 测试浏览器启动
    • 向 Antigravity 发送请求：”请打开 Chrome 浏览器”
    • 或使用浏览器相关的自动化任务
  2. 检查错误消息
    • 如果仍然报错，检查错误信息是否变化
    • 确认 HOME 环境变量在应用中生效
  3. 验证 Playwright 功能
    • 尝试访问网页、截图等浏览器操作
    • 确认浏览器自动化功能完全恢复

其他操作系统

Linux / macOS

在 Linux 和 macOS 系统上，HOME 环境变量通常已经默认设置。如果遇到类似问题，可以检查：

检查 HOME 变量：

1

echo $HOME

临时设置（当前会话）：

1

export HOME=/home/username

永久设置（添加到 shell 配置文件）：

1
2
3
4
5
6
7

# 对于 bash
echo 'export HOME=/home/username' >> ~/.bashrc
source ~/.bashrc

# 对于 zsh
echo 'export HOME=/home/username' >> ~/.zshrc
source ~/.zshrc

技术背景

为什么需要 HOME 环境变量？

HOME 环境变量在 Unix-like 系统中是标准的用户主目录指示符，用于：

  • 配置文件存储：应用程序在 $HOME 下创建 .config、.cache 等目录
  • 浏览器配置：Playwright 在 $HOME/.cache/ms-playwright 存储浏览器二进制
  • 跨平台兼容性：许多跨平台工具依赖 HOME 来定位用户空间资源

Antigravity 版本差异

版本 Playwright 行为 HOME 变量要求
1.14.x 自动降级到 USERPROFILE 可选
1.15.8 严格依赖 HOME 必需

这一变化可能是为了：

  • 提高跨平台一致性
  • 简化浏览器配置管理
  • 与上游 Playwright 库保持同步

常见问题（FAQ）

Q1: 设置了 HOME 变量，但仍然报错怎么办？

A: 确保以下几点：

  1. 已完全关闭并重新启动 Antigravity（环境变量对已运行进程无效）
  2. HOME 路径不包含特殊字符或空格，如果包含空格，确保使用完整路径
  3. 路径存在且当前用户有访问权限

Q2: 可以使用其他路径代替用户文件夹吗？

A: 可以，但建议使用标准用户文件夹路径（C:\Users\<用户名>）。如果使用自定义路径：

  • 确保路径存在
  • 确保有读写权限
  • 避免使用网络驱动器或受保护的系统目录

Q3: 这个设置会影响其他应用程序吗？

A: 可能会，某些应用程序也会读取 HOME 环境变量。通常情况下影响是正面的，因为：

  • 使 Windows 系统行为更接近 Unix-like 系统
  • 改善跨平台工具的兼容性
  • 不会与现有的 USERPROFILE 变量冲突

Q4: 每次系统重启都需要重新设置吗？

A: 不需要。通过”系统属性 → 环境变量”设置的变量会永久保存，除非手动删除。

预防措施

为避免未来遇到类似问题，建议：

  1. 标准化环境配置
    • 在开发机器上统一设置 HOME 环境变量
    • 记录团队的标准环境配置
  2. 监控工具更新
    • 关注 Antigravity 的发布说明
    • 在生产环境部署前进行充分测试
  3. 配置备份
    • 定期导出环境变量配置
    • 使用配置管理工具（如 Ansible）自动化环境设置

参考资料

总结

Antigravity 1.15.8 版本对 HOME 环境变量的依赖是一个明确的变更，反映了工具向跨平台标准化的演进。通过在 Windows 系统上正确设置 HOME 环境变量，可以快速解决 Chrome 浏览器启动失败的问题。

这个小小的配置调整不仅解决了当前问题，还为未来使用其他依赖 HOME 变量的跨平台工具铺平了道路。对于 Windows 用户来说，这是一个值得添加到标准开发环境配置清单中的设置项。

关键词： Antigravity、Chrome 浏览器、Playwright、环境变量、Windows 配置、浏览器自动化、故障排除