秒悟Meoo 生成的前后端项目如何配置环境变量

秒悟Meoo生成的前后端项目，环境变量配置的核心问题不是“变量怎么写”，而是“写进哪个文件、由哪段代码在什么时候加载”。前端变量必须带 VITE_ 前缀才会被打包工具暴露，后端变量则直接读取 process.env。如果改完配置不生效，多半是文件类型、变量前缀或加载顺序出了问题。

适用于秒悟Meoo生成的前后端分离项目；操作上先定位 .env 系列文件，区分前端 VITE_ 变量与后端 process.env 变量，用 dotenv 在入口加载，通过 cross-env 向命令行传递；验证时用 console.log 打印关键变量并检查空格污染。前端严禁放入密钥，否则会被打包进浏览器代码。

定位生成项目中的环境变量文件

生成项目通常包含多个环境变量文件。默认的 .env 存放所有环境共享的变量；.env.development 和 .env.production 分别存放开发、生产环境专用变量。启动命令会按当前 NODE_ENV 或模式加载对应文件，优先级一般是实际环境文件覆盖默认文件。

定位方法：打开 package.json，查看 scripts 中启动命令是否带 `--mode` 或 NODE_ENV 设置；在入口文件（如 src/main.js、server.js）中查看是否有 import 'dotenv/config' 或 require('dotenv').config({ path: ... })。如果代码里手动指定了路径，变量就放在那个路径下；否则使用项目根目录的默认文件。

区分前端变量与后端变量

前端变量必须用 VITE_ 开头，例如 VITE_API_BASE_URL。在 .env.development 中写入后，前端代码里用 import.meta.env.VITE_API_BASE_URL 读取。只有带 VITE_ 前缀的变量才会被 Vite 打包进客户端代码，其他变量不会暴露。

# .env.development (前端)
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=秒悟Meoo开发站

// 前端代码中读取
const apiBase = import.meta.env.VITE_API_BASE_URL;

后端变量直接读 process.env，例如在 .env 中写 PORT=8080，后端代码中 const port = process.env.PORT || 3000。后端变量不要加 VITE_ 前缀，否则可能被误打包。

设置数据库连接串与端口参数

数据库连接串和端口是后端启动时必须读到的变量。在 .env 文件中按以下格式存放：

# .env (后端)
DATABASE_URL=postgres://user:password@localhost:5432/meoo_db
PORT=8080
JWT_SECRET=your-secret-key

在代码中读取并传给连接池或 HTTP 服务：

// server.js 或 db.js
const pg = require('pg');
const db = new pg.Pool({ connectionString: process.env.DATABASE_URL });
const port = process.env.PORT || 3000;
app.listen(port, () => console.log(`Server on :${port}`));

注意：连接串中的特殊字符（@、#、?）需要用 URL 编码，否则解析可能失败。

在启动前正确加载变量

确保 dotenv 在入口文件最先加载。如果使用 CommonJS，在文件顶部写 require('dotenv').config()；如果使用 ES Module，写 import 'dotenv/config'。加载必须在读取任何 process.env 之前，否则变量还是 undefined。

// 入口文件最前面
import 'dotenv/config';
// 然后才 import 其他模块

对于 npm script，可以使用 cross-env 在命令中传递变量，兼容 Windows 和 Linux。例如：

"scripts": {
  "dev": "cross-env NODE_ENV=development node server.js",
  "build": "cross-env NODE_ENV=production vite build"
}

cross-env 需要先安装：npm install `--save-dev` cross-env。

验证变量是否被程序读取

改完配置后，最直接的验证方式是在代码里临时输出关键变量。在后端入口文件加一行：

console.log('DATABASE_URL:', process.env.DATABASE_URL);
console.log('PORT:', process.env.PORT);

在前端代码里加：

console.log('VITE_API_BASE_URL:', import.meta.env.VITE_API_BASE_URL);

然后启动开发服务器，观察控制台输出。与配置文件对比，确认值一致且没有多余空格。如果输出 undefined，检查变量是否写错文件名、变量名是否有前缀错误，或 dotenv 是否在读取前加载。如果值前后有空格，去掉后重启。