AstroJS环境变量问题：process未定义及生产环境import.meta.env失效

一、dotenv报错process is not defined的原因与修复 #

原因 #

dotenv是为Node.js环境设计的工具，用于将.env文件内容加载到process.env中，但浏览器客户端代码不存在process对象，若在Astro的客户端组件/代码中引入dotenv，就会触发该错误。

修复方案 #

• 服务端代码使用dotenv（不推荐）：如果是在Astro的API路由、SSR页面/组件（仅服务端运行的代码）中使用，需确保代码仅在服务端执行：

  export const prerender = false; // 禁用预渲染，确保在服务端运行
  // 或用Astro内置的isServer判断
  import { isServer } from 'astro';
  if (isServer) {
    import('dotenv').then((dotenv) => dotenv.config());
  }
  

  但更推荐直接使用Astro内置的环境变量处理能力，无需额外引入dotenv。
• 客户端代码禁用dotenv：客户端代码不能使用dotenv，改用Astro的PUBLIC_前缀环境变量方案。

二、import.meta.env在Docker生产构建中显示undefined的解决 #

Astro基于Vite，环境变量遵循Vite规则，结合Docker部署需注意以下几点：

1. 遵循Vite环境变量命名规则 #

• 客户端可访问的变量必须添加PUBLIC_前缀，比如PUBLIC_STRIPE_PUBLISHABLE_KEY，Vite会在构建时自动将其注入客户端代码。
• 服务端专用变量（如Stripe密钥）无需前缀，仅能在服务端代码中访问。

2. Docker构建/运行时传递环境变量 #

构建时注入（静态站点/预渲染模式）

在Dockerfile中通过ARG和ENV传递构建时变量：

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
# 接收构建参数并设置为环境变量
ARG PUBLIC_STRIPE_PUBLISHABLE_KEY
ENV PUBLIC_STRIPE_PUBLISHABLE_KEY=$PUBLIC_STRIPE_PUBLISHABLE_KEY
RUN npm run build
EXPOSE 4321
CMD ["npm", "run", "preview"]

在docker-compose.yml中配置构建参数：

services:
  astro-app:
    build:
      context: .
      args:
        - PUBLIC_STRIPE_PUBLISHABLE_KEY=${PUBLIC_STRIPE_PUBLISHABLE_KEY}
    ports:
      - "4321:4321"

运行时注入（SSR模式）

如果是Astro SSR模式，可直接在docker-compose.yml中设置环境变量，运行时Astro会读取：

services:
  astro-app:
    build: .
    environment:
      - PUBLIC_STRIPE_PUBLISHABLE_KEY=${PUBLIC_STRIPE_PUBLISHABLE_KEY}
      - STRIPE_SECRET_KEY=${STRIPE_SECRET_KEY}
    ports:
      - "4321:4321"

3. 确保环境变量优先级 #

Docker中设置的环境变量优先级高于本地.env文件，生产环境建议不要将.env文件打包进容器，避免敏感信息泄露。

三、哪种方案更适合存储Stripe发布密钥 #

优先选择Astro内置的import.meta.env（带PUBLIC_前缀），理由如下：

• 适配Astro/Vite生态，无需额外依赖，避免环境兼容问题。
• 天然区分客户端/服务端变量：Stripe发布密钥本身允许暴露给客户端，加PUBLIC_前缀后可安全在客户端代码中使用。
• 支持构建时注入和运行时读取，适配静态部署、SSR等多种部署模式，配合Docker更顺畅。

dotenv仅适合纯Node.js服务端场景，Astro已内置环境变量处理能力，无需额外引入，且客户端使用会触发错误，因此不推荐。

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