前置:第一次运行。排查顺序是位置 → 工具 → 配置 → 服务 → 请求 → 数据,避免一出错就重装整个环境。
命令与安装#
| 现象 | 检查 | 修复后怎么验证 |
|---|---|---|
| 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运行;未安装工具链时如实记录未跑,不伪造通过。
最后复查:用同一个最小请求证明修复。记录“错误 → 原因 → 改动 → 验证结果”,比只记“重启好了”更能支持后续学习。