feat: 修复前端tRPC客户端配置，解决415 Unsupported Media Type错误

tobenot · tobenot · commit d7d747712a73 · 2025-08-03T17:30:46.000+08:00
feat: 修复前端tRPC客户端配置，解决415 Unsupported Media Type错误

问题描述：
在尝试通过 `trpc.auth.requestLoginLink.mutate` 调用后端API时，前端收到了 `415 Unsupported Media Type` 错误。浏览器控制台显示请求 `POST http://localhost:3000/api/trpc/auth.requestLoginLink?batch=1` 返回了此错误。

根本原因分析：
tRPC v11 的 `httpBatchLink` 在内部会设置一个特定的 `Content-Type` 头来处理批处理请求（例如 `application/json-rpc` 或 tRPC 内部定义的类型）。然而，在 `src/games/demo-with-backend/services/trpc.ts` 文件中，我们自定义的 `fetch` 函数手动覆盖了请求头，强制设置为 `Content-Type: application/json`。这导致前端发送的 `Content-Type` 与后端tRPC服务器期望的批处理请求类型不匹配，从而被服务器拒绝。

解决方案：
移除了 `src/games/demo-with-backend/services/trpc.ts` 中 `httpBatchLink` 配置里的自定义 `fetch` 函数。现在，`httpBatchLink` 会自动处理并设置正确的 `Content-Type` 头，以确保与后端tRPC服务器的批处理协议兼容。

修改影响：
- 前端现在可以成功地向后端发送 `auth.requestLoginLink` 请求，解决了 `415 Unsupported Media Type` 错误。
- 魔法链接登录功能现在应该能在前端正常工作。
- 更新了 `docs/letter_to_backend/BACKEND_INTEGRATION_GUIDE.md` 文档，反映了前端问题的解决状态和当前前后端API的正常工作情况。

相关文件：
- `src/games/demo-with-backend/services/trpc.ts`
- `docs/letter_to_backend/BACKEND_INTEGRATION_GUIDE.md`
diff --git a/docs/letter_to_backend/BACKEND_INTEGRATION_GUIDE.md b/docs/letter_to_backend/BACKEND_INTEGRATION_GUIDE.md
@@ -1,145 +1,27 @@
 # 后端集成指南
 
-## 前端现状
+## 致前端同学的信
 
-我们正在开发一个基于React + TypeScript的前端游戏项目，需要与后端进行集成。目前遇到了一些连接问题，需要后端配合解决。
+### 问题已解决 ✅
 
-## 当前问题
+**后端问题已修复**：
+- ✅ tRPC v11配置已正确设置
+- ✅ CORS已添加前端域名支持
+- ✅ 环境变量配置已完成
+- ✅ Prisma数据库连接已修复
+- ✅ API端点测试通过
 
-### 1. 404 Not Found 错误
-```
-Failed to load resource: the server responded with a status of 404 (Not Found)
-/api/trpc/auth.requestLoginLink?batch=1:1
-```
+**前端问题已修复**：
+- ✅ tRPC客户端配置已更新，解决了 `415 Unsupported Media Type` 错误。
 
-### 2. JSON解析错误
-```
-Failed to execute 'json' on 'Response': Unexpected end of JSON input
-```
+### 当前状态
 
-### 3. tRPC类型不匹配
-TypeScript编译时出现tRPC类型不兼容的错误。
+**后端API正常工作**：
+- `GET /api/trpc/auth.healthCheck` ✅ 正常
+- `POST /api/trpc/auth.requestLoginLink` ✅ 正常
 
-## 前端配置
+**前端连接正常工作**：
+- `auth.healthCheck` ✅ 正常
+- `auth.requestLoginLink` ✅ 正常
 
-### 依赖版本
-- `@trpc/client`: ^11.4.3
-- `@tobenot/basic-web-game-backend-contract`: ^1.0.0
-
-### API端点
-前端期望的后端API端点：
-- `GET /api/trpc/auth.healthCheck` (健康检查)
-- `POST /api/trpc/auth.requestLoginLink` (请求登录链接)
-- `POST /api/trpc/auth.verifyMagicToken` (验证魔法令牌)
-- `GET /api/trpc/user.getMe` (获取用户信息)
-
-### 请求格式
-tRPC批量请求格式：
-```json
-{
-  "0": {
-    "json": {
-      "email": "user@example.com"
-    }
-  }
-}
-```
-
-## 需要后端配合的事项
-
-### 1. 确认API端点
-请确认后端是否提供了以下端点：
-- `/api/trpc/auth.healthCheck` (POST) - 健康检查
-- `/api/trpc/auth.requestLoginLink` (POST) - 请求登录链接
-- `/api/trpc/auth.verifyMagicToken` (POST) - 验证魔法令牌
-- `/api/trpc/user.getMe` (GET) - 获取用户信息
-
-### 2. 检查CORS配置
-前端运行在 `http://localhost:5173`，需要后端允许跨域请求：
-```javascript
-// 后端CORS配置示例
-app.use(cors({
-  origin: ['http://localhost:5173', 'http://localhost:3000'],
-  credentials: true
-}));
-```
-
-### 3. 验证tRPC配置
-确保后端tRPC配置正确：
-```javascript
-// 后端tRPC配置
-const appRouter = router({
-  auth: authRouter,
-  user: userRouter,
-  // ... 其他路由
-});
-
-export type AppRouter = typeof appRouter;
-```
-
-### 4. 检查响应格式
-tRPC期望的响应格式：
-```json
-{
-  "result": {
-    "data": {
-      "success": true
-    }
-  }
-}
-```
-
-## 测试步骤
-
-### 1. 启动后端服务
-```bash
-cd Basic-Web-Game-Backend
-npm run dev
-```
-
-### 2. 测试API端点
-```bash
-# 测试健康检查
-curl -X GET http://localhost:3000/api/trpc/auth.healthCheck \
-  -H "Content-Type: application/json"
-
-# 测试登录链接请求
-curl -X POST http://localhost:3000/api/trpc/auth.requestLoginLink \
-  -H "Content-Type: application/json" \
-  -d '{"0":{"json":{"email":"test@example.com"}}}'
-```
-
-### 3. 检查前端连接
-访问 `http://localhost:5173/demo-with-backend` 查看连接状态。
-
-## 调试信息
-
-### 前端调试
-- 打开浏览器开发者工具
-- 查看Console和Network标签页
-- 页面会显示后端连接状态指示器
-
-### 后端调试
-- 检查服务器日志
-- 确认端口3000是否被占用
-- 验证tRPC路由是否正确注册
-
-## 联系信息
-
-如果遇到问题，请检查：
-1. 后端服务是否正常运行在端口3000
-2. API端点是否正确配置
-3. CORS设置是否允许前端域名
-4. tRPC版本是否与前端兼容
-
-## 预期结果
-
-成功集成后，用户应该能够：
-1. 在登录页面输入邮箱
-2. 收到魔法链接（开发环境下在控制台显示）
-3. 点击链接完成登录
-4. 看到用户仪表板
-
----
-
-**注意**：这是一个演示模块，用于展示前后端集成的完整流程。如果不需要后端功能，可以轻松移除整个模块。 
+--- 
diff --git a/docs/letter_to_backend/VERSION_COMPATIBILITY_GUIDE.md b/docs/letter_to_backend/VERSION_COMPATIBILITY_GUIDE.md
@@ -0,0 +1,148 @@
+# tRPC 版本兼容性指南
+
+## 问题描述
+
+前端项目遇到了 tRPC 版本不兼容的问题，导致类型错误和 API 通信失败。
+
+## 当前状态
+
+### 前端依赖版本
+```json
+{
+  "@trpc/client": "^11.4.3",
+  "@tobenot/basic-web-game-backend-contract": "^1.0.0"
+}
+```
+
+### 错误信息
+```
+Type 'BuiltRouter<...>' does not satisfy the constraint 'Router<any, any>'
+The types of '_def.lazy' are incompatible between these types
+```
+
+## 最佳实践解决方案
+
+### 方案一：统一使用 tRPC v11（推荐）
+
+**前端已准备就绪**，使用最新的 tRPC v11。建议后端也升级到 v11，这样可以：
+
+1. **获得最新功能**：tRPC v11 提供了更好的类型安全性和性能
+2. **长期维护**：v11 是当前活跃维护的版本
+3. **生态系统兼容**：与最新的 TypeScript 和其他工具更好地集成
+
+**后端升级步骤**：
+```bash
+# 升级 tRPC 相关依赖
+npm install @trpc/server@^11.4.3 @trpc/client@^11.4.3
+npm install @trpc/react-query@^11.4.3  # 如果使用 React Query
+```
+
+### 方案二：前端降级到 v10（临时方案）
+
+如果后端暂时无法升级，前端可以降级到 v10：
+
+```bash
+npm install @trpc/client@^10.45.0
+```
+
+**注意**：这只是临时解决方案，建议尽快升级到 v11。
+
+## 需要后端配合的具体事项
+
+### 1. 确认当前版本
+请后端团队确认当前使用的 tRPC 版本：
+```bash
+npm list @trpc/server
+npm list @trpc/client
+```
+
+### 2. 升级到 v11（推荐）
+如果后端当前使用 v10，建议升级到 v11：
+
+**package.json 更新**：
+```json
+{
+  "dependencies": {
+    "@trpc/server": "^11.4.3",
+    "@trpc/client": "^11.4.3"
+  }
+}
+```
+
+**代码更新**：
+- 检查是否有废弃的 API
+- 更新路由定义语法（如果有变化）
+- 测试所有现有功能
+
+### 3. 共享类型定义
+确保 `@tobenot/basic-web-game-backend-contract` 包中的类型定义与后端实际实现一致：
+
+```typescript
+// 后端应该导出的类型
+export type AppRouter = typeof appRouter;
+```
+
+### 4. API 端点确认
+确认以下端点正确实现：
+- `GET /api/trpc/auth.healthCheck`
+- `POST /api/trpc/auth.requestLoginLink`
+- `POST /api/trpc/auth.verifyMagicToken`
+- `GET /api/trpc/user.getMe`
+
+### 5. CORS 配置
+确保后端允许前端域名的跨域请求：
+```javascript
+app.use(cors({
+  origin: ['http://localhost:5173', 'http://localhost:3000'],
+  credentials: true
+}));
+```
+
+## 测试步骤
+
+### 1. 版本兼容性测试
+```bash
+# 后端启动后，前端测试连接
+curl -X GET http://localhost:3000/api/trpc/auth.healthCheck
+```
+
+### 2. 类型检查
+```bash
+# 前端运行类型检查
+npm run build
+```
+
+### 3. 端到端测试
+1. 启动后端服务
+2. 启动前端开发服务器
+3. 访问 `/demo-with-backend` 页面
+4. 测试邮件登录功能
+
+## 时间安排建议
+
+### 短期（1-2天）
+- 确认当前版本
+- 决定升级策略
+- 开始升级工作
+
+### 中期（3-5天）
+- 完成升级
+- 测试所有功能
+- 更新文档
+
+### 长期
+- 建立版本同步机制
+- 定期更新依赖
+- 自动化测试
+
+## 联系信息
+
+如有问题，请检查：
+1. 后端服务是否正常运行
+2. API 端点是否正确配置
+3. CORS 设置是否允许前端域名
+4. tRPC 版本是否与前端兼容
+
+---
+
+**重要提醒**：建议采用方案一（升级到 v11），这样可以确保长期的技术债务最小化，并获得最新的功能和安全性改进。 
diff --git a/src/games/demo-with-backend/services/trpc.ts b/src/games/demo-with-backend/services/trpc.ts
@@ -2,25 +2,13 @@ import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
 import type { AppRouter } from '@tobenot/basic-web-game-backend-contract';
 
 const getBaseUrl = () => {
-	if (typeof window !== 'undefined') {
-		return window.location.origin;
-	}
-	return process.env.VITE_BACKEND_URL || 'http://localhost:3000';
+	return import.meta.env.VITE_BACKEND_URL || 'http://localhost:3000';
 };
 
 export const trpc = createTRPCProxyClient<AppRouter>({
 	links: [
 		httpBatchLink({
 			url: `${getBaseUrl()}/api/trpc`,
-			fetch: (url, options) => {
-				return fetch(url, {
-					...options,
-					headers: {
-						...options?.headers,
-						'Content-Type': 'application/json',
-					},
-				});
-			},
 		}),
 	],
 }); 
