From 9b882b4752e6f03f6c2bdf667688cebbd84889ef Mon Sep 17 00:00:00 2001 From: yiliang114 <1204183885@qq.com> Date: Thu, 12 Feb 2026 12:55:26 +0800 Subject: [PATCH] wip --- PR_DESCRIPTION_ZH.md | 53 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 PR_DESCRIPTION_ZH.md diff --git a/PR_DESCRIPTION_ZH.md b/PR_DESCRIPTION_ZH.md new file mode 100644 index 000000000..5b25639a0 --- /dev/null +++ b/PR_DESCRIPTION_ZH.md @@ -0,0 +1,53 @@ +## TLDR + +修复在容器环境（如 code-server 远程开发）中，IDE 客户端因 `host.docker.internal` 域名不可达而无法连接的问题。 + +将 `getIdeServerHost()` 函数改为异步，在检测到容器环境后，先通过 DNS 查询验证 `host.docker.internal` 是否可解析，不可达时自动回退到 `127.0.0.1`。 + +## Dive Deeper + +### 问题背景 + +在 Docker Desktop 中，`host.docker.internal` 会自动配置为指向宿主机的特殊域名。但在以下环境中该域名不一定存在： + +- **Linux Docker**：需要手动添加 `--add-host=host.docker.internal:host-gateway` +- **code-server 远程环境**：不运行在 Docker Desktop 中，没有该域名 +- **Podman 等其他容器运行时**：不一定支持该域名 + +原有实现只通过 `/.dockerenv` 或 `/run/.containerenv` 文件检测是否在容器中，一旦检测到就直接使用 `host.docker.internal`，但未验证该域名是否实际可达，导致在上述环境中 IDE 连接失败。 + +### 修改内容 + +1. **`getIdeServerHost()` 改为异步函数**：新增 `dns.lookup` 检查 `host.docker.internal` 是否可解析 +2. **结果缓存**：首次检测结果缓存到模块级变量 `cachedIdeServerHost`，避免重复 DNS 查询 +3. **debug 日志**：在容器环境下输出 DNS 检查结果，方便排查连接问题 +4. **导出测试辅助函数**：`_resetCachedIdeServerHost()` 用于测试间隔离缓存状态 +5. **完整单元测试**：新增 6 个测试用例覆盖所有场景 + +### 修改文件 + +| 文件 | 变更 | +| ------------------------------------------ | ------------ | +| `packages/core/src/ide/ide-client.ts` | 核心逻辑修改 | +| `packages/core/src/ide/ide-client.test.ts` | 新增测试用例 | + +## Reviewer Test Plan + +1. 拉取分支后运行测试：`npx vitest run packages/core/src/ide/ide-client.test.ts` +2. 确认所有 24 个测试通过（含 6 个新增） +3. 在 Docker 容器中（有 `host.docker.internal`）验证 IDE 连接正常 +4. 在 code-server 远程环境中（无 `host.docker.internal`）验证 IDE 自动回退到 `127.0.0.1` + +## Testing Matrix + +| | 🍏 | 🪟 | 🐧 | +| -------- | --- | --- | --- | +| npm run | ✅ | ❓ | ❓ | +| npx | ❓ | ❓ | ❓ | +| Docker | ❓ | ❓ | ❓ | +| Podman | ❓ | - | - | +| Seatbelt | ❓ | - | - | + +## Linked issues / bugs + +