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

前置：[第一次运行](../01-beginner/04-first-run.md)。排查顺序是位置 → 工具 → 配置 → 服务 → 请求 → 数据，避免一出错就重装整个环境。

## 命令与安装

| 现象 | 检查 | 修复后怎么验证 |
| --- | --- | --- |
| 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运行；未安装工具链时如实记录未跑，不伪造通过。

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