Files

T

yinjianm 96d9950c6b feat(frontend): 重构本地调试代理配置

将 `packages/frontend` 的 Vite 开发代理改为可通过环境变量
切换目标地址，并补充本地联调所需的默认主题与样式更新。
同时同步更新前后端默认 UI 主题定义，便于在本地直接验证
远端接口、WebSocket 与视觉效果。

2026-04-21 05:15:18 +08:00

5.2 KiB

Raw Permalink Blame History

变更提案: frontend-dev-api-theme-verification

元信息

类型: 优化
方案类型: implementation
优先级: P1
状态: 已完成
创建: 2026-04-21

1. 需求

背景

用户要求将本地前端联调请求切到 https://ssh.deiban.com，重点验证 /api/v1/settings/focus-switcher-sequence 这类设置接口是否能通过本地前端正确访问，并使用 admin / @Micah.666 登录后确认此前“默认前端白色主题”改动是否真实生效。

目标

仅调整本地开发联调入口，不改动前端生产默认 API 地址。
让本地 packages/frontend 在开发模式下统一代理远端 https://ssh.deiban.com。
完成一次真实浏览器登录与页面视觉验收，确认白色主题是否生效，并给出结论。

约束条件

时间约束: 当前回合内完成代码改动与联调验证
性能约束: 不引入额外运行时开销，保持 Vite 代理方案
兼容性约束: 现有相对路径 API 调用保持不变，本地切换后仍可回退到 localhost:3001
业务约束: 仅作用于本地开发联调，不覆盖共享生产配置

验收标准

[√] 本地前端开发环境可将 /api、/uploads、/ws 请求代理到 ssh.deiban.com
[√] 使用 admin / @Micah.666 可从本地前端完成登录并访问登录后页面
[√] 浏览器实测能判断白色主题是否生效，并能给出成功或失败的证据

2. 方案

技术方案

保留前端现有的相对路径请求方式，不改 apiClient 和 store 内部接口地址。将 packages/frontend/vite.config.ts 改为支持从本地开发环境变量读取 dev proxy 目标，默认仍指向 localhost:3001。同时新增忽略提交的 packages/frontend/.env.development.local，把本地开发代理目标切换到 https://ssh.deiban.com / wss://ssh.deiban.com，并显式设置 VITE_API_BASE_URL 供页面背景等直接拼接后端 URL 的逻辑使用。完成后启动本地 Vite，并用浏览器执行登录和主题验收。

影响范围

涉及模块:
  - frontend: 调整本地开发代理配置与运行时联调环境变量
预计变更文件: 4

风险评估

风险	等级	应对
远端站点 WebSocket 目标与本地代理协议不兼容	中	同步提供 `VITE_DEV_WS_PROXY_TARGET`，保持与 HTTP 代理解耦
远端管理员账号存在用户级外观配置，导致白色主题判断受后端数据影响	中	同时检查登录页和登录后页面样式来源，区分默认主题与后端覆盖
本地环境变量文件被忽略后不在 Git 记录中	低	在最终结果中明确说明本地文件路径与用途

3. 技术设计（可选）

本次不涉及架构、API 或数据模型变更。

架构设计

N/A

API设计

N/A

数据模型

N/A

4. 核心场景

执行完成后同步到对应模块文档

场景: 本地前端联调远端测试后端

模块: frontend 条件: 开发者在 packages/frontend 启动本地 Vite 开发服务器行为: 前端通过本地代理将 /api、/uploads、/ws 请求转发到 ssh.deiban.com 结果: 无需改动业务代码中的相对路径接口即可完成远端联调

场景: 登录后验收默认白色主题

模块: frontend 条件: 使用管理员账号登录本地前端行为: 检查登录页与登录后页面的背景、文字和主容器配色结果: 能明确判断白色主题是否生效，以及是否被后端持久化外观配置覆盖

5. 技术决策

本方案涉及的技术决策，归档后成为决策的唯一完整记录

frontend-dev-api-theme-verification#D001: 使用可配置的 dev proxy 而非写死远端 API

日期: 2026-04-21 状态: ✅采纳背景: 需要将本地前端切到远端测试后端验证主题效果，但不应把共享开发默认值永久改成远端地址。 选项分析:

选项	优点	缺点
A: 直接把 `vite.config.ts` 写死到 `ssh.deiban.com`	改动最少，立刻可用	污染团队默认开发配置，回切需要再次改代码
B: 让 `vite.config.ts` 读取环境变量，再用 `.env.development.local` 本地覆盖	保持默认本地后端联调，同时支持当前远端测试	需要新增一个本地环境变量文件
决策: 选择方案 B
理由: 既满足当前本地调试诉求，又不破坏仓库共享默认值，后续切回本地后端只需改本地环境变量。
影响: 影响 `packages/frontend/vite.config.ts` 的开发代理读取方式，以及本地开发环境变量文件组织方式

6. 成果设计

含视觉产出的任务由 DESIGN Phase2 填充。非视觉任务整节标注"N/A"。

本任务不新增视觉设计，仅验证既有白色主题是否已经生效。

设计方向

美学基调: N/A
记忆点: N/A
参考: 现有前端默认白色主题实现

视觉要素

配色: N/A
字体: N/A
布局: N/A
动效: N/A
氛围: N/A

技术约束

可访问性: 保持现有主题变量与文本对比度，不在本任务中新增样式覆盖
响应式: 仅做桌面浏览器联调验证

5.2 KiB Raw Permalink Blame History