xpzouying/xiaohongshu-mcp · critical

下载内置浏览器失败: %w 本项目只用内置浏览器，缺它不继续。请检查网络后重试； 离线环境可手动下载 %s，解压

Error message

下载内置浏览器失败: %w
  本项目只用内置浏览器，缺它不继续。请检查网络后重试；
  离线环境可手动下载 %s，解压到 %s 后重启。

What it means

EnsureBrowser 连续 3 次下载内置浏览器压缩包均失败（每次失败已删除半成品文件并间隔 2s 重试）。本项目只使用内置浏览器、不回退系统浏览器，所以网络不可用即无法继续；错误中附带手动下载 URL 与缓存目录供离线环境自救。

Source

Thrown at browser/browser_download.go:104

	if err := os.MkdirAll(cacheDir, 0o755); err != nil {
		return "", err
	}

	// 下载（重试 3 次）
	logrus.Infof("首次运行：下载内置浏览器 %s（%s，约 140-190MB，仅一次）...", browserVersion, asset)
	archivePath := filepath.Join(cacheDir, asset)
	var dlErr error
	for attempt := 1; attempt <= 3; attempt++ {
		if dlErr = downloadFile(browserURL(asset), archivePath); dlErr == nil {
			break
		}
		logrus.Warnf("下载失败（第 %d/3 次）: %v", attempt, dlErr)
		_ = os.Remove(archivePath)
		time.Sleep(2 * time.Second)
	}
	if dlErr != nil {
		return "", fmt.Errorf("下载内置浏览器失败: %w\n"+
			"  本项目只用内置浏览器，缺它不继续。请检查网络后重试；\n"+
			"  离线环境可手动下载 %s，解压到 %s 后重启。", dlErr, browserURL(asset), cacheDir)
	}
	defer os.Remove(archivePath)

	// 校验 SHA256（本地已成分发点，必须校验完整性）
	if err := verifySHA256(archivePath, asset); err != nil {
		return "", fmt.Errorf("校验失败: %w", err)
	}

	logrus.Infof("解压内置浏览器 ...")
	if err := extractArchive(archivePath, cacheDir); err != nil {
		return "", fmt.Errorf("解压失败: %w", err)
	}

	bin := findBinary(cacheDir, binName)
	if bin == "" {
		return "", fmt.Errorf("解压后未找到二进制 %s", binName)

View on GitHub (pinned to 332d196854)

Solutions

  1. 检查网络连通性后重试
  2. 按错误信息中的 URL 手动下载资产，解压到提示的缓存目录后重启
  3. 配置正确的代理环境变量（HTTPS_PROXY/HTTP_PROXY）
  4. 容器环境安装 ca-certificates

Example fix

// before
./app # 下载失败
// after
export HTTPS_PROXY=http://proxy:8080
./app # 或手动下载 asset 解压到 UserCacheDir 下的缓存目录后重启
Defensive patterns

Strategy: retry

Validate before calling

// 下载前探测网络可达
resp, err := http.Head(assetURL)
if err != nil { return fmt.Errorf("网络不可达: %w", err) }
resp.Body.Close()

Try / catch

bin, err := browser.EnsureBrowser()
if err != nil && strings.Contains(err.Error(), "下载内置浏览器失败") {
	slog.Warn(err.Error()) // 错误信息含手动下载 URL 与缓存目录
	return manualFallback()
}

Prevention

When it happens

Trigger: 浏览器资产下载 3 次均失败：无外网/防火墙拦截下载域名、DNS 解析失败、代理不可用、下载服务器 5xx、带宽中断导致超时。

Common situations: 离线/内网服务器部署；公司代理未配置 HTTPS_PROXY；下载 CDN 临时故障；容器内缺少 CA 证书导致 TLS 失败。

Related errors

AI-assisted analysis of xpzouying/xiaohongshu-mcp@332d196854 (2026-09-05). Data as JSON: /api/errors/47a8a7bbd5f85349. Report an issue: GitHub.