# 依赖与环境：在新版本和成熟度之间取舍

查询日期：2026-11-14（Asia/Shanghai）。版本来源为官方 Go 下载 JSON、Node 发布 JSON、npm registry 和 Go module proxy 的版本元数据。锁定值以根 go.mod/go.sum、frontend/package.json/package-lock.json 和 .node-version 为准，不依赖读者运行当天的 latest。

## 实际选择

| 项 | 原状态 | 本次锁定 | 原因 |
| --- | --- | --- | --- |
| 后端语言 | JDK/Spring Cloud 多模块 | Go 1.26.11 | 官方同时有 1.27.4，选仍受支持的上一稳定分支最新补丁 |
| Node | 本机 24.11.1 | 24.22.3 LTS | 保留 24 LTS 主线，更新补丁；项目本地安装，不改全局 |
| React / React DOM | 18.3.1 | 19.3.1 | 同版本配对，组件构建与浏览器回归通过 |
| Vite | 5.4.10 | 7.3.8 | 官方 registry 最新为 8.3.8；选成熟 7.x 补丁，避免同时进入新构建器主线 |
| plugin-react | 4.3.1 | 5.2.0 | 与选定 Vite 7 配套，不混用要求 Vite 8 的 6.x |
| TypeScript | 5.6.3 | 5.9.3 | registry 最新为 7.0.2；保留成熟 5.x 语义，控制重构变量 |
| @types/react / dom | 18.x | 19.3.0 | 类型与 React 19 运行时同步 |
| @types/node | 未显式固定 | 24.19.2 | 对应 Node 24 主线 |
| lucide-react | 0.468.0 | 0.577.0 | 当前 1.x 已发布，保留成熟 0.x，验证已有图标导出 |
| GSAP | 3.12.5 | 3.15.1 | 保留 3.x API、matchMedia 与减少动画处理 |
| modernc.org/sqlite | 新增 | 1.62.0 | 纯 Go，无需 Windows C 编译器；当前 Go 1.26 工具链兼容 |
| golang-jwt/jwt/v5 | 新增 | 5.3.1 | 使用维护中的 v5、固定算法与 claims 验证 |
| golang.org/x/crypto | 新增 | 0.59.0 | bcrypt，及时跟进安全修复；通过 govulncheck |
| golang.org/x/term | 新增 | 0.48.0 | 仅密码哈希工具使用，隐藏终端输入 |

主线较新不意味着每个依赖都必须降一个大版本。工具链/前端构建器优先控制主线变动，密码学和数据库驱动则优先当前维护版本与安全检查。没有为“最新”牺牲已有功能，也没有只保留多年未更新版本。

## 本次实际处理的兼容问题

1. Windows SQLite URI：盘符 `D:` 必须生成合法 `file:///D:/...`，原写法会报 invalid uri authority。已修复并由 Windows 集成测试覆盖。
2. 前端代理：原来网关、搜索、上传三个端口改为单个 `/api`；开发环境代理 `/api` 和 `/uploads`，构建后同源访问。
3. React 19 与类型包：同步更新 runtime/types，严格 TypeScript 编译通过。未依赖已移除的 ReactDOM.render。
4. 管理员分页：去掉旧 `unwrap:false` 特例，规范响应只在 API 封装解包一次。
5. 发布返回：保留后端真实 noteId 和作者，替换发布后 Date.now 假 ID；评论也重新读取真实记录。
6. 演示开关：默认 false，真实环境不会先显示演示列表作为假成功。
7. 登录失效：旧 Java token/demo-token 无 Go session，401 时清除旧凭证并引导重新登录。
8. 搜索枚举：前端排序 0最新/1赞/2评论/3收藏与后端一致；时间筛选转换为 1天/2周/3半年，避免 0 被误当未选。
9. 随机验证码：开发回传 debugCode 并自动填入，生产不回传；不沿用“填任意六位码”原型说明。
10. 标题/昵称 HTML：取消不可信 dangerouslySetInnerHTML，避免搜索输出和依赖变更扩大 XSS 面。
11. 图片与字体：默认页面使用本地摄影和系统字体，构建后不再依赖 Google Fonts/外部图片可用性。

## 重现安装

```powershell
go mod download
go mod verify
npm.cmd ci --prefix frontend
```

go.sum 记录依赖内容校验和；package-lock 记录 npm 精确依赖图。手工只改 package.json 不更新锁文件，会让 npm ci 失败，这是可复现安装应有的保护。不要用 `npm audit fix --force` 自动跨主线改版本。

## 如何以后升级

先写出当前版本、目标版本、最低运行时和发布说明，再只改一组相互匹配的依赖。跑 go test、go vet、go mod verify、前端构建、npm audit、govulncheck 和浏览器业务检查；检查验证码、发布 ID、分页、文件上传、401 和私密可见性。保存结果后再改下一组。性能与行为变化需单独记录，不能把编译通过当迁移验证完成。

## 来源与核对命令

官方来源：<https://go.dev/dl/?mode=json>、<https://nodejs.org/dist/index.json>、<https://registry.npmjs.org/vite>、<https://registry.npmjs.org/typescript>、<https://proxy.golang.org>。源码中实际模块内容由 Go 校验，地区网络不可用时可以为当前命令临时设置 GOPROXY，但不要永久改全局环境或关闭 sumdb。

本次本地执行 `govulncheck` 使用 v1.9.0，结果在验证报告中。漏洞库随时间变化，未来检查发现新问题时应更新处理，不能把 2026-11-14 的结果当永久保证。
