.env 配置手册

本文档详细说明项目根目录下 .env 文件的配置项，包括环境标识、端口、URL、CORS 等参数的含义和使用方法。

用于指定项目运行环境，由自动化脚本自动注入或手动修改。

变量名	可选值	说明
`NODE_ENV`	`development`	开发环境（本地开发时使用，启用热更新、详细日志）
	`production`	生产环境（线上部署时使用，优化性能、关闭调试功能）

示例：

# 生产环境
NODE_ENV=production

仅在 NODE_ENV=development 时生效，用于本地开发调试。

变量名	默认值	说明
`DEV_FRONTEND_PORT`	`5174`	前端 VitePress 开发服务器端口（避免与其他服务冲突）
`DEV_BACKEND_PORT`	`3003`	后端 API 服务开发端口
`DEV_API_URL`	`http://localhost:${DEV_BACKEND_PORT}/api`	前端请求的后端 API 基础路径（动态拼接后端端口）
`DEV_BASE_URL`	`/`	前端路由基础路径（本地开发通常为根路径）

示例：

# 开发环境前端端口改为 8080
DEV_FRONTEND_PORT=8080
# 开发环境 API 地址
DEV_API_URL=http://localhost:3003/api

仅在 NODE_ENV=production 时生效，用于线上部署。

变量名	默认值	说明
`PROD_FRONTEND_PORT`	`80`	前端服务端口（如使用 Nginx 反向代理，可保持默认 80）
`PROD_BACKEND_PORT`	`3001`	后端 API 服务端口（生产环境建议使用非 80/443 端口）
`PROD_API_URL`	`http://xxx.xx.xx.xx`	前端请求的后端 API 地址（生产服务器公网 IP/域名）
`PROD_BASE_URL`	`/`	前端路由基础路径（如部署在子路径下，需改为 `/subpath/`）
`PROD_CHUNK_SIZE_WARNING_LIMIT`	`1000`	前端构建时 Chunk 大小警告阈值（KB），超过此值会提示优化

示例：

# 生产环境 API 域名
PROD_API_URL=https://api.example.com
# 生产环境前端子路径部署
PROD_BASE_URL=/docs/

在开发/生产环境均生效，用于统一配置站点基础信息。

变量名	默认值	说明
`SHARED_TITLE`	`我的VitePress文档`	站点标题（显示在浏览器标签页和首页）
`SHARED_LOGO_PATH`	`/assets/icons/logo.jpg`	Logo 图片路径（基于 `public` 目录，无需加 `public` 前缀）
`SHARED_OUTLINE_TITLE`	`章节导航`	右侧大纲面板标题
`SHARED_DOC_FOOTER_PREV`	`上一页`	文档底部“上一页”按钮文本
`SHARED_DOC_FOOTER_NEXT`	`下一页`	文档底部“下一页”按钮文本

示例：

# 自定义站点标题和Logo
SHARED_TITLE=EAI Node.js 模板文档
SHARED_LOGO_PATH=/assets/logo-custom.png

用于控制后端 API 跨域访问权限（仅后端服务生效）。

变量名	默认值	说明
`CORS_ORIGIN`	`http://localhost:5174`	允许跨域请求的前端域名（生产环境建议指定具体域名，如 `https://docs.example.com`）
`CORS_METHODS`	`GET,POST,PUT,DELETE`	允许的 HTTP 请求方法
`CORS_ALLOWED_HEADERS`	`Content-Type,Authorization,X-Custom-Header`	允许的请求头（如需要自定义 headers，需在此添加）

示例：

# 生产环境允许所有域名跨域（不推荐，仅测试用）
CORS_ORIGIN=*
# 仅允许 GET 和 POST 方法
CORS_METHODS=GET,POST

用于自动化脚本的路径和文件配置。

变量名	默认值	说明
`TMP_PACK_DIR`	`deploy/app`	构建产物临时打包目录（脚本内部使用，无需手动修改）
`FINAL_OUTPUT`	`dist/app.tar.gz`	最终打包输出路径（用于部署的压缩包位置）

示例：

# 自定义打包输出路径
FINAL_OUTPUT=dist/deploy.tar.gz

敏感信息：.env 文件不应提交敏感信息（如数据库密码），生产环境建议通过服务器环境变量注入
路径规范：SHARED_LOGO_PATH 需指向 public 目录下的文件，如 public/assets/icons/logo.jpg 对应路径 /assets/icons/logo.jpg
端口冲突：开发时若提示端口被占用，修改 DEV_FRONTEND_PORT 或 DEV_BACKEND_PORT 为未占用端口

通过修改 .env 文件，可灵活适配不同环境需求，无需修改代码即可切换配置。