dashboard/.qoder/repowiki/knowledge/zh/后端 .env + 前端 Vite 环境变量双轨配置体系/后端 .env + 前端 Vite 环境变量双轨配置体系.md

kind, name, category, scope, source_files

kind	name	category	scope	source_files
configuration_system	后端 .env + 前端 Vite 环境变量双轨配置体系	configuration_system	**	backend/src/config/loadEnv.js backend/src/config/env.js backend/src/config/database.js backend/src/config/redis.js backend/src/config/logger.js backend/src/app.js .env.example frontend_v2/.env frontend_v2/vite.config.ts

系统概览

本仓库采用「后端 Node.js + 前端 Vue3/Vite」前后端分离的单体部署模式，配置系统分为两条独立轨道：

• 后端：基于 dotenv 从根目录 .env 加载，通过 process.env 注入；启动时由 src/config/loadEnv.js 统一读取。
• 前端（v2）：基于 Vite 的 loadEnv，按 VITE_ 前缀暴露给浏览器，支持多环境文件 .env / .env.prod / .env.test。

关键文件与包

• backend/src/config/loadEnv.js — 项目入口最先执行，解析根目录 .env（Docker 场景下由 compose env_file 覆盖）。
• backend/src/config/env.js — 提供 APP_ENV、isDevelopment、isProduction 三个布尔/字符串常量，供各模块判断运行环境。
• backend/src/config/database.js — Sequelize 连接串，所有 MySQL 参数均走 DATABASE_* 环境变量，开发默认 localhost:3306/audio/root/root123。
• backend/src/config/redis.js — ioredis 客户端单例工厂 getEqCacheRedis()，通过 REDIS_HOST/PORT/PASSWORD/EQ_DB 控制，带错误日志与重连策略。
• backend/src/config/logger.js — winston 实例，固定输出到 backend/logs/app.log 与控制台，无运行时可配级别。
• backend/src/app.js — 应用入口，先 require('./config/loadEnv') 再挂载中间件、路由，最后以 process.env.PORT 监听。
• backend/.env.example — 完整的环境变量清单（数据库、JWT、Meilisearch、S3、OTA URL、Curve API、Redis 等），是部署时的权威参考。
• frontend_v2/.env / .env.prod / .env.test — Vite 构建期环境变量，全部以 VITE_ 前缀命名，被 vite.config.ts 通过 loadEnv 读取并注入到 define/server.proxy 中。
• frontend_v2/vite.config.ts — 使用 loadEnv(configEnv.mode, process.cwd()) 加载对应环境的 .env*，并将 base、proxy、sourcemap 等构建选项与之一一对应。

架构与约定

1. 加载顺序：app.js → require('./config/loadEnv') → dotenv.config({ path: root/.env }) → 后续各 config/*.js 直接读 process.env。这保证了在 Docker 中以 env_file 注入的变量优先级高于本地 .env。
2. 环境标识：仅依赖单一变量 APP_ENV（development | production），不提供 staging 等中间态；各模块用 isDevelopment/isProduction 做分支逻辑（如 Sequelize logging、OTA 上传目录回退到系统临时目录）。
3. 配置分层：没有集中式配置对象，每个子系统（DB、Redis、Logger、JWT、S3、OTA URL）各自在自己的 config 文件中按需读取 process.env，形成“分散但自描述”的配置结构。
4. 前端隔离：Vite 只把 VITE_ 前缀的变量注入到客户端代码，敏感信息不会进入产物；后端变量与前端变量完全解耦，避免泄露风险。
5. 默认值策略：所有关键配置都提供合理的本地开发默认值（MySQL root/root123、Redis 空密码、端口 8083/9527），保证克隆后 pnpm dev 即可运行。

开发者应遵循的规则

• 新增环境变量：先在根目录 .env.example 补充条目与注释，再在对应 config/*.js 或 vite.config.ts 中消费；不要硬编码路径或密钥。
• 区分环境：通过 APP_ENV 切换行为，不要在业务代码里写死 if (process.env.NODE_ENV) 之类的判断。
• 安全边界：任何包含密钥、密码、私钥的变量一律不进源码，仅出现在 .env.example（占位值）和 CI/CD 的 secrets 中；前端变量必须以 VITE_ 开头。
• Docker 优先：容器内不依赖 .env 文件，所有变量应由 docker-compose.yml 的 environment/env_file 注入；本地开发才使用根目录 .env。
• 前端构建期变量：修改 VITE_* 需要重新 build，而非热重载生效；生产环境通过 .env.prod 控制打包产物。