vue工程运行、构建、引用环境参数学习记录

1. Vite 环境文件变量命名规则

在 Vue 项目的环境文件中，所有的环境变量必须以 VITE_ 开头。例如：

VITE_APP_ENV='development'

2. 将环境变量传递给 vite.config.js

如果你想让 vite.config.js 加载环境变量并传递给 HTML 文件，可以在 vite.config.js 中使用 define 来定义全局变量。

define: {
  'process.env': {
    VITE_APP_BASE_ICO: JSON.stringify(env.VITE_APP_BASE_ICO),
    VITE_APP_BASE_SYSTEM_NAME: JSON.stringify(env.VITE_APP_BASE_SYSTEM_NAME),
  },
}

3. 在 HTML 中使用环境变量

在 HTML 文件中，使用 JavaScript 动态加载环境变量来设置网页的标题和图标。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="icon" href="" id="favicon">
  <title id="page-title">Default System Name</title>
</head>
<body>
  <script>
    // 动态设置网页标题和图标
    const favicon = document.getElementById('favicon');
    const pageTitle = document.getElementById('page-title');

    // 通过 `window.process.env` 获取环境变量
    const icoPath = window.process?.env?.VITE_APP_BASE_ICO || '/default-icon.ico';
    const systemName = window.process?.env?.VITE_APP_BASE_SYSTEM_NAME || 'Default System Name';

    if (favicon) favicon.href = icoPath;
    if (pageTitle) pageTitle.textContent = systemName;
  </script>
</body>
</html>

4. 解决赋值时机问题

如果全局变量 window.process?.env?.VITE_APP_BASE_SYSTEM_NAME 在控制台中可以正确输出，但在 const 变量中赋值时为 undefined，这可能是因为 赋值时机 的问题。

可能原因：

1. 变量尚未注入到 window 对象。
2. 脚本加载顺序导致访问变量时它还未被定义。

解决方案：增加一个事件监听器，确保在 DOM 完成加载后再获取和设置环境变量：

document.addEventListener('DOMContentLoaded', () => {
  const icoPath = window.process?.env?.VITE_APP_BASE_ICO || '/default-icon.ico';
  const systemName = window.process?.env?.VITE_APP_BASE_SYSTEM_NAME || 'Default System Name';

  console.log('Favicon Path:', icoPath);
  console.log('Page Title:', systemName);

  const favicon = document.getElementById('favicon');
  if (favicon) favicon.href = icoPath;

  const pageTitle = document.getElementById('page-title');
  if (pageTitle) pageTitle.textContent = systemName;
});

5. 根据环境变量动态改变 logo 图片路径

在 Vue 组件中，可以使用 import.meta.env 来访问 Vite 配置的环境变量，并动态设置 logo 路径。

错误用法 ：直接在环境文件中定义路径时，不能使用 @ 作为别名：

VUE_APP_LOGO_PATH = '@/assets/logo/wollox.png'  // 错误

正确用法 ：使用相对路径并以 VITE_ 开头：

VITE_APP_LOGO_PATH = '/assets/logo/wollox.png'

在 logo.vue 中使用环境变量：

<img v-if="logo" :src="logo" class="sidebar-logo" />

<script setup>
import variables from '@/assets/styles/variables.module.scss'
import useSettingsStore from '@/store/modules/settings'

// 从环境变量读取 logo 路径，若未定义则使用默认路径
const logoPath = import.meta.env.VITE_APP_LOGO_PATH || '@/assets/logo/default-logo.png';

// 动态导入 logo 图片，确保路径能够被解析
const logo = new URL(logoPath, import.meta.url).href;

const title = import.meta.env.VITE_APP_TITLE;
const settingsStore = useSettingsStore();
const sideTheme = computed(() => settingsStore.sideTheme);
</script>

6. 解决 npm run dev 和 npm run prod 的差异

为什么 npm run dev 能直接启动 Vite 工程，但 npm run prod 却不能启动生产环境？

问题原因：

这是因为在 package.json 中没有正确配置生产环境的参数。

解决方案：

在 package.json 中配置 scripts：

"scripts": {
  "dev": "vite",
  "prod": "vite --mode production",
  "release": "vite --mode release",
  "build:prod": "vite build --mode production",
  "build:release": "vite build --mode release",
  "build:stage": "vite build --mode staging",
  "preview": "pnpm build && vite preview"
}

• vite：启动 Vue 工程的开发模式，默认是 development 环境。
• vite build：构建 Vue 工程，生成静态文件，通常用于生产环境。
• --mode：指定要使用的环境配置文件，VITE_APP_ENV='production' 或 VITE_APP_ENV='development' 等。

通过设置 --mode production，确保 VITE_APP_ENV 为 production 环境，Vite 会根据配置文件加载正确的环境变量进行构建。