Astro项目编译时如何指定使用.env.development环境变量文件？

问题根源 #

Astro默认会根据运行模式自动匹配对应环境变量文件：development模式加载.env.development，production模式加载.env.production。但执行astro build时，Astro会强制将NODE_ENV设为production，这会覆盖你通过--mode指定的模式逻辑，导致始终读取.env.production。

解决方法 #

方法一：显式设置NODE_ENV并指定模式

修改package.json的build脚本，先强制设置NODE_ENV=development，再搭配--mode development参数：

"scripts": {
  "dev": "astro dev",
  "start": "astro dev",
  "build": "NODE_ENV=development astro check && astro build --mode development",
  "preview": "astro preview",
  "astro": "astro"
}

• Windows系统需替换为set NODE_ENV=development；
• 要跨平台兼容，可先安装cross-env依赖（npm i cross-env -D），脚本改为：

  "build": "cross-env NODE_ENV=development astro check && astro build --mode development"
  

方法二：直接指定env文件路径（Astro v2.10+支持）

如果你的Astro版本是2.10或更高，可直接通过--env-file参数指定目标文件，无需纠结模式冲突：

"scripts": {
  "dev": "astro dev",
  "start": "astro dev",
  "build": "astro check && astro build --env-file .env.development",
  "preview": "astro preview",
  "astro": "astro"
}

额外检查项 #

• 确认.env.development文件名无拼写错误（比如不要写成.env.dev或漏写开头的点）；
• 客户端需访问的变量必须以PUBLIC_为前缀（如PUBLIC_API_BASE=http://dev.server.com），服务端变量无需前缀；
• 执行build前可删除node_modules/.cache目录，避免缓存的旧环境变量干扰。

内容的提问来源于stack exchange，提问作者Edwin Aquino