沙箱参数会自动补上
多数 Linux 容器没有可用的 setuid 沙箱。Chromium 会在调试端口绑定之前就退出,会话失败而且看不出原因。 当 Extension.js 识别出这种环境时,它会给 Chromium 启动补上--no-sandbox 和 --disable-setuid-sandbox。识别条件是平台为 Linux,并且满足以下任意一项:
CI变量的值为字符串true。- 存在
/.dockerenv文件,由 Docker 创建。 - 存在
/run/.containerenv文件,由 Podman 创建。 REMOTE_CONTAINERS变量由 VS Code 设为true。CODESPACES变量由 GitHub Codespaces 设为true。container变量由若干 Linux 运行时设置。
平台判断也是条件的一部分。运行在 macOS 或 Windows
宿主上的容器报告的平台不同,因此那里不会补上这些参数。
browserFlags 配置项和 EXTENSION_BROWSER_FLAGS 变量见浏览器参数。
把开发服务器绑定到所有网卡
开发服务器默认绑定127.0.0.1,容器外的任何进程都访问不到。传入 --host 0.0.0.0 改为绑定所有网卡:
127.0.0.1,在你把端口转发到宿主机时这是正确的值。ready.json 中的 host 字段报告的就是这个可连接地址,而不是绑定地址。
当浏览器必须用别的名字访问容器时,显式传入:
让浏览器留在宿主机
没有显示环境的容器无法启动浏览器。用--no-browser 只启动开发服务器,然后在你自己的浏览器里加载编译产物:
dist/<browser>/,例如 dist/chromium/。在宿主机上把该目录作为未打包扩展加载。端口转发完成后,重载仍然会通过开发服务器送达。
绑定挂载下的文件监视
Extension.js 默认使用原生文件系统事件监视,因为轮询会唤醒 CPU 并拖慢重载。在拥有自己文件系统的容器里,原生事件是可靠的。 出问题的是来自 macOS 或 Windows 宿主的绑定挂载。这类挂载常常丢事件,宿主机上的改动到不了编译器。这时请打开轮询:EXTENSION_WATCH_POLL_INTERVAL 设为另一个毫秒值。
容器会话检查清单
- 把开发服务器端口转发到宿主机。
- 用
--host 0.0.0.0启动会话。 - 容器内没有浏览器时加上
--no-browser。 - 改动经由绑定挂载传入时加上
EXTENSION_WATCH_POLL=true。
后续步骤
- 阅读浏览器参数,了解 Extension.js 传入的参数。
- 阅读在 WSL 下开发扩展,了解 Windows 上的对应做法。
- 阅读 CI 模板,了解构建服务器上的无头运行。

