小蓝书 Go
测试与验收

常见问题:从现象找到最小原因

前置:第一次运行。排查顺序是位置 → 工具 → 配置 → 服务 → 请求 → 数据,避免一出错就重装整个环境。

命令与安装#

现象 检查 修复后怎么验证
go / node不是命令 Get-Command、重新开终端 安装官方工具或项目bootstrap后再次输出版本
npm.ps1被策略拦截 是否写成npm而非npm.cmd 使用npm.cmd,不永久放宽全局策略
找不到go.mod Get-Location 回根目录再go test
npm ci锁文件不一致 package.json是否只改未重装 审查版本改动、npm install更新锁,再ci
Node引擎不匹配 node –version、.node-version 用Node24;脚本优先.tools/node
Go下载工具链失败 GOTOOLCHAIN、代理、网络 保持auto;只为当前命令临时设置可用GOPROXY,不关sumdb
中文脚本语法错误 PowerShell5.1与文件编码 ps1保存UTF-8带BOM,再调用脚本;不是删中文业务逻辑

服务与页面#

端口占用:查看服务日志的 bind 错误,用 Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue 查监听。确认是谁占用,选择别的HTTP_ADDR;不要按端口批量杀陌生进程。Vite strictPort=true,5173占用时也明确失败。

首页503“前端未构建”:运行 npm.cmd ci --prefix frontend、npm.cmd run build --prefix frontend,检查frontend/dist/index.html存在。后端API健康不代表页面产物一定已生成。

页面404但health正常:确认打开的是根路径,代码是否已重新编译。曾经的Windows根路径.被误认为有扩展名的问题已修复;新代码构建后不能继续运行旧exe来验证。

“没有返回JSON”:常见是API_BASE或Vite代理错误,请求被SPA兜底返回HTML。Network看地址、状态、响应Content-Type;使用本项目/api规范,不再让搜索去原8092端口。

登录与账号#

验证码错误:重新获取,注意5分钟有效、只用一次、5次尝试限制;开发自动填码只在本地环境返回。生产未接短信适配器会拒绝启动或502,不会悄悄用固定码绕过。

已有token却401:旧Java签名、demo-token、密钥变更、session删除或账号停用都可能导致。正常重新登录,不去数据库手工给自己加admin。不要把浏览器解码出admin=true当权限证据。

默认管理员密码不对:默认仅用于首次初始化;已有管理员哈希不会被启动默认值重置。检查自己使用的是哪个DATABASE_PATH,是否曾修改密码。恢复应使用可信备份/经过验证的管理流程,不能为了登录清空实际库。

数据与文件#

SQLite locked:确认是不是多个写进程同时连接同一实际库、是否有调试器长时间持事务、rows是否未Close。开发只启动一套当前服务。busy_timeout=5秒不是无限排队保证,长事务要缩短。

invalid uri authority D::这是Windows盘符URI解析问题,新database.Open会构造合法file:///路径;如果仍出现,确认运行的是新构建产物。

头像保存刷新后变旧:查API返回avatar是不是/uploads而非blob,资料更新是否成功,是否仍在运行旧前端dist。当前前端用后端返回Profile更新,不把临时blob作为持久地址。

图片404:确认上传URL与UPLOAD_DIR匹配、文件存在、反向代理没有截掉/uploads。数据库备份不包含文件内容,恢复时必须同时恢复uploads。默认摄影在public/assets,需随前端构建复制。

私密笔记图片直链仍能看:当前上传目录公开,私密只限制笔记与评论。这是已说明的媒体访问边界;严格私密资源要设计授权媒体读取,不是隐藏一个按钮就完成。

测试与磁盘#

govulncheck超时:检查漏洞库网络,不能当无漏洞通过。浏览器下载失败/临时盘空间不足:将PLAYWRIGHT_BROWSERS_PATH、TEMP和TMP指向项目.tools下的独立目录再重试,不删除系统或其他项目缓存。本次浏览器仅为开发验证,普通运行不依赖它。

覆盖率某包0%:跨包集成测试需加-coverpkg=./…,详见测试章节。race提示需要CGO:这是额外动态检测依赖,不影响默认纯GoSQLite运行;未安装工具链时如实记录未跑,不伪造通过。

最后复查:用同一个最小请求证明修复。记录“错误 → 原因 → 改动 → 验证结果”,比只记“重启好了”更能支持后续学习。

— 本篇阅读完毕 —
来源:小蓝书 Go / docs / 04-testing/troubleshooting.md 下载原文
输入关键词,在三个知识库中搜索
支持正文检索 · 直接定位章节Esc 关闭