Vitepress 项目中使用环境变量的正确方式

在基于 Vitepress 构建文档网站时，环境变量的使用是一个常见需求，特别是在需要保护敏感信息（如 API 密钥、服务 ID 等）的场景下。本文将详细介绍如何在 Vitepress 项目中正确配置和使用环境变量。

环境变量的基本配置

Vitepress 基于 Vite 构建，因此继承了 Vite 的环境变量处理机制。要使用环境变量，开发者需要遵循以下规则：

1. 文件命名规范：环境变量文件必须以 .env 开头，例如 .env、.env.development 或 .env.production

2. 变量命名前缀：只有以 VITE_ 开头的变量才会被 Vite 暴露给客户端代码

3. 文件位置：环境变量文件必须放置在 Vitepress 的工作目录中（通常是 docs/ 目录）

常见问题解决方案

许多开发者会遇到环境变量无法加载的问题，这通常是由于以下原因造成的：

1. 文件位置错误：将 .env 文件放在了项目根目录而非 Vitepress 工作目录（如 docs/）

2. 变量命名不规范：没有使用 VITE_ 前缀，导致变量未被暴露

3. 开发服务器未重启：修改 .env 文件后没有重启开发服务器

实际应用示例

假设我们需要在 Vitepress 项目中使用 Giscus 评论系统，其中包含一些敏感 ID 信息。正确的做法是：

1. 在 docs/ 目录下创建 .env 文件：

VITE_GISCUS_DATA_REPO="your-repo-name"
VITE_GISCUS_DATA_REPO_ID="your-repo-id"
VITE_GISCUS_DATA_CATEGORY="Announcements"
VITE_GISCUS_DATA_CATEGORY_ID="your-category-id"

2. 在 Vue 组件中通过 import.meta.env 访问这些变量：

const repoId = import.meta.env.VITE_GISCUS_DATA_REPO_ID
const categoryId = import.meta.env.VITE_GISCUS_DATA_CATEGORY_ID

高级配置建议

对于更复杂的场景，开发者还可以考虑：

1. 多环境配置：使用 .env.development 和 .env.production 分别配置开发和生产环境变量

2. 类型安全：通过环境变量类型声明文件增强 TypeScript 支持

3. 构建优化：在构建时将环境变量直接内联，减少运行时开销

总结

Vitepress 的环境变量使用遵循 Vite 的规范，关键在于正确放置 .env 文件和使用 VITE_ 前缀。通过本文介绍的方法，开发者可以安全高效地在 Vitepress 项目中使用环境变量，既保护了敏感信息，又保持了代码的灵活性。