Vitepress环境变量无法读取，如何正确配置与使用？

你遇到的问题核心是：.vitepress/config.mjs 运行在Node.js环境中，而 import.meta.env 是Vite为浏览器客户端环境提供的变量，Node环境中不存在该对象，所以会触发Cannot read properties of undefined错误。以下是两种可行的解决方式：

方式一：手动加载.env文件（推荐） #

1. 安装dotenv包，用于在Node环境中加载.env文件

npm install dotenv --save-dev

2. 修改.vitepress/config.mjs，在顶部加载对应环境的.env文件，并用process.env读取变量：

import dotenv from 'dotenv'
import { resolve } from 'path'

// 根据当前环境加载对应的.env文件
const envFilePath = process.env.NODE_ENV === 'production'
  ? resolve(__dirname, '../.env.production')
  : resolve(__dirname, '../.env')

dotenv.config({ path: envFilePath })

export default {
  lang: 'en-US',
  title: process.env.VITE_APP_TITLE,
  description: 'My doc.',
  head: [['link', { rel: 'icon', href: '/dp-docs/favicon.ico' }]],
  // 如果需要在客户端Markdown/Vue组件中使用这些变量，需通过vite.define暴露
  vite: {
    define: {
      'import.meta.env.VITE_APP_TITLE': JSON.stringify(process.env.VITE_APP_TITLE),
      'import.meta.env.VITE_APP_ENV': JSON.stringify(process.env.VITE_APP_ENV)
    }
  }
}

方式二：通过指定运行模式自动加载.env文件 #

Vitepress支持通过--mode参数指定运行模式，会自动加载对应模式的.env文件（比如--mode production会加载.env.production）：

1. 修改package.json中的scripts：

{
  "scripts": {
    "docs:dev": "vitepress dev --mode development",
    "docs:build": "vitepress build --mode production",
    "docs:preview": "vitepress preview --mode production"
  },
  "devDependencies": {
    "vitepress": "1.3.0"
  }
}

2. 修改.vitepress/config.mjs，用process.env读取变量：

export default {
  lang: 'en-US',
  title: process.env.VITE_APP_TITLE,
  description: 'My doc.',
  head: [['link', { rel: 'icon', href: '/dp-docs/favicon.ico' }]],
  // 客户端需要使用变量时，同样需要通过vite.define暴露
  vite: {
    define: {
      'import.meta.env.VITE_APP_TITLE': JSON.stringify(process.env.VITE_APP_TITLE),
      'import.meta.env.VITE_APP_ENV': JSON.stringify(process.env.VITE_APP_ENV)
    }
  }
}

注意事项 #

• Node环境中始终使用process.env读取环境变量，import.meta.env仅适用于浏览器客户端代码（比如Markdown中的脚本、Vue组件）。
• 所有需要在客户端使用的环境变量，必须通过vite.define显式暴露，否则客户端无法访问。

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