xpzouying/xiaohongshu-mcp · error

校验失败: %w

Error message

校验失败: %w

What it means

EnsureBrowser 下载完成后用官方 SHA256SUMS 校验压缩包完整性失败：文件在传输中被损坏或截断，也可能是下载源返回了错误页内容。校验是完整性保护的必要步骤，失败则放弃本次下载产物。

Source

Thrown at browser/browser_download.go:112

	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)
	}
	logrus.Infof("内置浏览器就绪: %s", bin)
	return bin, nil
}

// verifySHA256 下载同目录的 SHA256SUMS，校验 asset 的哈希。
func verifySHA256(archivePath, asset string) error {
	want, err := fetchExpectedSHA(asset)

View on GitHub (pinned to 332d196854)

Solutions

1. 删除缓存目录中损坏的压缩包后重跑（触发重新下载）
2. 确认 SHA256SUMS 的下载地址可达
3. 检查缓存目录读写权限

Example fix

// before
bin, err := browser.EnsureBrowser() // 校验失败
// after
if strings.Contains(err.Error(), "校验失败") {
	os.RemoveAll(cacheDir) // 清理损坏缓存
	bin, err = browser.EnsureBrowser()
}

// 下载后先用本地工具预校验
// sha256sum <archive> 与官方 SHA256SUMS 对比，一致再进入流程

bin, err := browser.EnsureBrowser()
if err != nil && strings.Contains(err.Error(), "校验失败") {
	os.RemoveAll(cacheDir) // 清理可疑缓存后重试
	bin, err = browser.EnsureBrowser()
}

When it happens

Trigger: verifySHA256 返回任何 error：下载的 SHA256SUMS 获取失败（fetchExpectedSHA 网络错误）、本地压缩包无法读取/打开、哈希计算 io.Copy 失败。

Common situations: 下载中断产生截断文件；SHA256SUMS 下载被防火墙拦截；缓存目录权限异常导致文件不可读。

Related errors

• SHA256SUMS 中未找到 %s
• %s SHA256 不匹配：期望 %s，实际 %s
• 获取 SHA256SUMS: HTTP %d
• invalid image URL format
• downloaded file is not a valid image

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