Frontend Technical Spec

技术设计规则（前端）

前置条件检测

在应用工具或框架相关规则之前，先检查 package.json、锁文件、TypeScript/构建配置、CI 定义以及具有代表性的组件。只有当仓库依据明确指出时，才可将 React、Vite、Next.js、状态库、表单库或脚本视为可用。将基于周边模式得出的结论标注为推断结果。当某个缺失的决策会影响渲染架构、兼容性、安全性或验证方式时，停下来并指出所需的具体依据或用户决策。

基础技术栈方针

以下规则适用于仓库配置已确认为基于 TypeScript 的 React 应用的情况。通过将当前需求与约束映射到组件职责、状态归属、服务端/客户端边界以及可观测的验证点来选择架构。

环境变量管理与安全

环境变量管理

• 使用构建工具的客户端暴露机制：浏览器代码只能读取由所配置的打包工具/框架明确暴露的值；仅服务端可访问的环境变量不会进入客户端包
• 通过配置层集中管理环境变量
• 在应用使用前，在一个类型化的配置边界处解析所有暴露的值
• 仅当需求中定义了值缺失时的有效行为时才为其设置默认值；否则应在启动/构建验证阶段失败，并给出变量名和期望格式

// 构建工具环境变量（仅限公开值；客户端暴露的变量需要 VITE_ 前缀）
const config = {
  apiUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000',
  appName: import.meta.env.VITE_APP_NAME || 'My App'
}

// 在前端中不可用
const apiUrl = process.env.API_URL

安全性（客户端约束）

• 关键：所有前端代码都是公开的，在浏览器中可见
• 将机密信息保留在服务端：客户端暴露的配置只应包含公开值；API 密钥、令牌和凭据应由后端或受信任的服务持有
• 将本地 .env 文件排除在版本控制之外，并为所需的变量名提供不含机密信息的示例文件
• 只记录和返回当前信任边界所批准的字段；对密码、令牌和个人数据进行脱敏

处理机密信息的正确方式：

// 安全风险：API 密钥在浏览器中暴露
const apiKey = import.meta.env.VITE_API_KEY
const response = await fetch(`https://api.example.com/data?key=${apiKey}`)