首页
/ CapRover 项目中 Vite 应用环境变量配置指南

CapRover 项目中 Vite 应用环境变量配置指南

2025-05-16 20:21:42作者:丁柯新Fawn

在 CapRover 平台上部署基于 Vite 构建的前端应用时,环境变量的正确配置是一个常见的技术挑战。本文将详细介绍如何解决环境变量在前端应用中显示为 undefined 的问题。

问题背景

当开发者使用 CapRover 部署 Vite 构建的 React 应用时,可能会遇到环境变量无法正确传递到前端的问题。具体表现为应用中读取的环境变量显示为 undefined,尽管这些变量已经在 CapRover 的管理界面中正确设置。

根本原因分析

这个问题的核心在于构建时环境变量和运行时环境变量的区别:

  1. 前端应用特性:前端代码运行在客户端浏览器中,无法直接访问服务器环境变量
  2. Vite 构建机制:Vite 需要在构建阶段将环境变量注入到前端代码中
  3. Docker 构建流程:CapRover 使用 Docker 容器部署应用,环境变量需要在构建阶段就可用

解决方案

修改 captain-definition 文件

关键是在 Docker 构建阶段通过 ARG 和 ENV 指令传递环境变量:

FROM node:18-alpine
WORKDIR /app
COPY ./package.json /app/
RUN npm install && npm cache clean --force
COPY ./ /app
ARG VITE_HELLO_WORLD
ENV VITE_HELLO_WORLD $VITE_HELLO_WORLD
ENV NODE_ENV production
RUN npm run build
CMD [ "npm","run", "preview" ]

技术要点说明

  1. ARG 指令:定义构建时可传递的参数,允许在构建时动态设置值
  2. ENV 指令:将构建参数转换为容器内的环境变量
  3. 构建时注入:确保 Vite 在构建阶段能访问到所需环境变量

最佳实践建议

  1. 变量命名规范:建议使用 VITE_ 前缀,这是 Vite 的默认约定
  2. 敏感信息处理:避免在前端代码中使用敏感环境变量
  3. 多环境配置:可以为不同环境创建不同的构建配置
  4. 类型安全:考虑使用类型定义文件为环境变量添加类型提示

总结

通过正确配置 Dockerfile 中的 ARG 和 ENV 指令,可以确保 Vite 应用在 CapRover 平台上能够正确获取和使用环境变量。这种解决方案不仅适用于 VITE_HELLO_WORLD 这个特定变量,也可以推广到其他需要在构建阶段注入的前端环境变量场景。

登录后查看全文
热门项目推荐
相关项目推荐