环境变量与 .env 配置

Mizuki 通过项目根目录的 .env 文件集中管理构建期与部署期的可配置项，涵盖内容仓库同步开关（代码/内容分离）、IndexNow SEO 提交凭据、Bilibili 会话数据等能力。本页说明 .env.example 模板结构、每个环境变量的语义与默认值、配置生效路径，以及本地开发与托管部署两条配置路线的安全边界。

Purpose and Scope

本页（getting-started / 环境变量与 .env 配置）覆盖以下内容：

.env.example 模板的分区结构与全部环境变量清单；
每个变量的语义、取值约束、默认值与生效条件；
本地 .env 与托管平台环境变量（Secrets）两条配置路径；
NODE_ENV 在 Astro 构建配置（astro.config.mjs）中的实际使用；
凭据管理红线（不将 .env 与真实凭据提交到 Git）。

以下相关主题有意留给兄弟页面，本页只做引导：

内容分离/同步机制的完整实现细节（.env.example 中引用了 docs/AUTO_BUILD_TRIGGER.md 的自动构建触发方案）——属于内容同步与部署相关页面；
站点业务配置（src/config/siteConfig.ts 及 src/config/ 下其他模块）——属于站点配置页面，README 明确将二者区分为"环境变量配置"与"代码内站点配置"两条路径。

Overview

Mizuki 是一个 Astro 博客主题。它的配置体系分为两层：

代码内站点配置：src/config/siteConfig.ts 等 TypeScript 模块，描述站点名称、URL、外观等长期业务属性；
环境变量（.env）：描述"随环境变化"的开关与凭据——是否启用内容仓库同步、指向哪个内容仓库、IndexNow 提交密钥、Bilibili 登录会话等。

仓库提供了 .env.example 作为唯一提交到 Git 的模板，其中每个变量都带有中文注释说明用途与取值方式。开发者通过 cp .env.example .env 复制模板后按需填写；.env 本身不进入版本库。README 对这一流程有明确要求：

环境变量配置（可选）： 可参照 .env.example 来配置 Source: README.md

典型使用场景：

本地内容模式（默认入门路径）：不启用内容分离，直接使用本地 content 目录，此时 .env 中 ENABLE_CONTENT_SYNC=false 或直接注释掉该行；
内容分离模式：将博客内容托管在独立 Git 仓库（示例：https://github.com/matsuzaka-yuki/Mizuki-Content），构建时同步内容；
SEO 提交：配置 INDEXNOW_KEY / INDEXNOW_HOST，向搜索引擎推送 URL 更新；
B 站观看进度展示：配置 BILI_SESSDATA 会话凭据。

Architecture

环境变量从"模板"到"生效"的整体路径如下图所示：

Loading diagram...

设计意图说明：

模板即文档：.env.example 把所有可配置项连同中文注释一起提交进仓库，任何新贡献者无需阅读源码即可知道"有哪些旋钮、每个旋钮怎么拧"。这是 12-Factor App 中"配置与代码分离"原则的落地方式——同一份代码在不同环境（本地/托管平台）通过不同变量值表现出不同行为。
双通道注入：本地开发走 .env 文件；托管构建（Vercel/Netlify 等平台）则由平台在构建进程注入环境变量，README 明确指出"托管构建请在平台的环境变量设置中配置"。
NODE_ENV 是框架级变量：astro.config.mjs 中仅有一处直接读取环境变量的代码——process.env.NODE_ENV === "production"，用于控制无障碍检测插件的 updateHead 行为只在生产构建启用。它不是用户需要手工设置的变量，而是由 Astro CLI / 构建平台自动提供。

需要如实说明的一点：本页在 src/ 的 ts / astro / mjs 源码中未检索到 import.meta.env 或 process.env 的直接引用；ENABLE_CONTENT_SYNC 等业务变量的消费发生在构建/内容同步流程与部署平台层面（其完整实现路径未在本页验证），本页的变量语义以 .env.example 注释与 README 文档为准。

环境变量清单（.env.example 完整解析）

.env.example 按功能分为四个区块，以下按文件原始顺序逐一说明。

1. 内容仓库配置（代码/内容分离）

dotenv

# 是否启用内容分离功能 (true/false)
# true: 启用内容分离,从独立仓库同步内容
# false: 禁用内容分离,使用本地内容 (默认模式)
# 注意: 如果不使用内容分离功能,可以注释掉或设置为 false
ENABLE_CONTENT_SYNC=false

# 内容仓库的 Git URL (仅在 ENABLE_CONTENT_SYNC=true 时需要)
# 支持 HTTPS 和 SSH 两种方式:
# HTTPS: https://github.com/your-username/Mizuki-Content.git
# SSH: git@github.com:your-username/Mizuki-Content.git
CONTENT_REPO_URL=https://github.com/your-username/Mizuki-Content.git

# 内容目录路径 (相对于项目根目录)
# 默认: ./content 一般无需改动
CONTENT_DIR=./content

Source: .env.example

这一组是 Mizuki "代码与内容分离"策略的控制面：

ENABLE_CONTENT_SYNC 是总开关。设为 false（或注释掉）即回到本地内容模式——README 将其列为推荐的入门方式：Set ENABLE_CONTENT_SYNC=false in a root .env file if you want to use only local content. Source: README.en.md
CONTENT_REPO_URL 只在开关为 true 时生效，支持 HTTPS 与 SSH 两种 Git 协议。注意示例地址指向主题作者的内容仓库 matsuzaka-yuki/Mizuki-Content（见 .env.example 第 6 行的项目地址注释），使用者需替换为自己的内容仓库。
CONTENT_DIR 定义内容落地目录，默认 ./content。

.env.example 第 25–31 行还预留了一个"自动构建触发"区块（本身不含变量），说明内容仓库更新不会自动触发代码仓库的部署，并指向 docs/AUTO_BUILD_TRIGGER.md 给出基于 Repository Dispatch 的 5 步配置方案——该机制的实现细节属于内容同步/部署页面，此处不展开。

2. IndexNow SEO 配置

dotenv

# IndexNow API 密钥，用于向搜索引擎提交 URL 更新
INDEXNOW_KEY=asdf1213456
# 网站主机地址
INDEXNOW_HOST=your.example.com

Source: .env.example

INDEXNOW_KEY：IndexNow 协议要求站点向搜索引擎证明所有权，密钥会随 URL 提交请求一并提供。
INDEXNOW_HOST：需要被推送的主机名。README 特别提醒这类凭据属于"可选配置，只在需要时设置，并放在本地环境或托管平台 Secret 中，切勿提交真实值"。 Source: README.md

3. Bilibili 会话数据

dotenv

# SESSDATA 的获取：
# 1. 登录 bilibili 账号
# 2. 打开浏览器开发者工具（F12 或 Ctrl+Shift+I）
# 3. 找到“应用程序”(app)一栏
# 4. 在请求头中查找 cookie 字段
# 5. 从 cookie 中提取 sessdata 值

# 环境变量名：BILI_SESSDATA     key值：sessdata
BILI_SESSDATA=your_bilibili_sessdata

Source: .env.example

BILI_SESSDATA 用于以登录态调用 B 站接口获取观看进度（模板注释将其与 cookie 中的 sessdata 键对应）。模板内嵌了 5 步获取指引，降低了配置门槛。这是全部变量中敏感度最高的一项——它等同于账号会话凭据，因此只能放在本地 .env 或托管平台 Secret 中。

4. 框架级变量 NODE_ENV

javascript

updateHead: process.env.NODE_ENV === "production",
updateBodyClass: false,

Source: astro.config.mjs

这是 src/ 之外唯一一处直接读取环境变量的构建代码，位于 astro.config.mjs 的无障碍检测（accessibility）插件配置中：仅当 NODE_ENV 为 production 时才开启 updateHead（同时在第 132 行可见 accessibility: true 常开）。设计意图是让构建产物级别的无障碍修复只在生产构建发生，避免本地开发热更新时被头部改写干扰。用户无需手工设置 NODE_ENV——它由 Astro CLI（astro build）或托管平台自动注入。

Configuration Options

变量	取值类型	默认 / 示例值	是否必填	说明
`ENABLE_CONTENT_SYNC`	布尔字符串	`false`（默认模式）	否	`true` 启用内容仓库分离同步；`false`/注释掉则使用本地 `content` 目录
`CONTENT_REPO_URL`	Git URL 字符串	`https://github.com/your-username/Mizuki-Content.git`	仅当 `ENABLE_CONTENT_SYNC=true`	内容仓库地址，支持 HTTPS 与 SSH（`git@github.com:...`）
`CONTENT_DIR`	相对路径	`./content`	否	内容同步落地目录（相对项目根），一般无需改动
`INDEXNOW_KEY`	字符串	示例占位 `asdf1213456`	否	IndexNow 提交 URL 时使用的站点所有权密钥
`INDEXNOW_HOST`	主机名字符串	`your.example.com`	否	需推送更新通知的站点主机名
`BILI_SESSDATA`	字符串（敏感凭据）	占位值	否	B 站登录会话 `sessdata`，用于获取观看进度；严禁提交到 Git
`NODE_ENV`	`production` / `development`	由 CLI / 平台注入	否（自动化）	仅在 `astro.config.mjs` 中控制无障碍 `updateHead` 行为

注意：除 NODE_ENV 外，上述业务变量在 src/**/*.{ts,astro,mjs} 源码中未检索到直接引用，其消费发生在构建期内容同步流程或部署平台侧；语义以上表（源自 .env.example 注释）为准。

核心流程：本地与部署两条配置路线

Loading diagram...

两条路线的详细步骤（源自 README）：

本地路线：cp .env.example .env 后编辑，需要启用内容分离时把 ENABLE_CONTENT_SYNC 置为 true。 Source: README.tw.md
部署路线：部署前在 src/config/siteConfig.ts 更新 siteURL；.env 与凭据不进 Git，托管构建改在平台环境变量中配置。 Source: README.md

Usage Examples

本地内容模式（入门推荐）

dotenv

# 本地内容模式（推荐入门使用）
# 在 .env 中明确关闭同步
ENABLE_CONTENT_SYNC=false

Source: README.tw.md

仅使用本地 content 目录时，这一行就是全部必需配置；其余区块（IndexNow、B 站）均可注释掉。

启用内容分离模式

bash

# 1. 复制配置示例
cp .env.example .env
# 2. 编辑 .env
ENABLE_CONTENT_SYNC=true

Source: README.tw.md

启用后还需填写 CONTENT_REPO_URL（HTTPS 或 SSH 地址）；模板注释指出默认 CONTENT_DIR=./content 通常无需修改。

Failure Modes, Edge Cases & Security

基于源码与 README 证据可确认的边界与风险：

场景	后果 / 处理方式	依据
忘记复制模板、`.env` 缺失	`ENABLE_CONTENT_SYNC` 未定义时按模板注释等价于"注释掉 = 默认关闭"，回落到本地内容模式	.env.example
将 `.env` 或真实凭据提交到 Git	README 明确禁止："不要将 `.env` 或凭据提交到 Git"	README.md
`BILI_SESSDATA` 泄露	等同于 B 站账号会话泄露；只能存放于本地 `.env` 或托管平台 Secret	.env.example
内容仓库已更新但站点未重建	`.env.example` 明确指出"内容仓库更新不会自动触发代码仓库的部署"，需按 `docs/AUTO_BUILD_TRIGGER.md` 配置 Repository Dispatch	.env.example
托管平台误以为会读取 `.env`	平台构建应使用环境变量面板注入，而非依赖仓库内文件	README.md

敏感值分级：BILI_SESSDATA（账号会话）> INDEXNOW_KEY（站点所有权证明）> CONTENT_REPO_URL（若为私有仓库则含访问语义，SSH 形式依赖本机密钥而非凭据本身）。所有真实凭据一律不得写入提交到 Git 的文件。

Performance / Operational Notes

本地 vs 生产的差异化行为：astro.config.mjs 中 updateHead: process.env.NODE_ENV === "production" 意味着无障碍检测的头部修复只发生在生产构建，本地热更新不受影响，也不会把开发期的诊断头部改写带进源码。
可选配置的取舍：IndexNow 与 B 站区块按需启用，不配置即不参与相应功能，避免无意义的网络调用与凭据暴露面。
运维关注点：内容分离模式下，同步与部署解耦是主要运维成本；docs/AUTO_BUILD_TRIGGER.md 的 5 步 Repository Dispatch 方案是官方推荐的闭环手段（详见内容同步相关页面）。

Extension Points

若需新增自定义环境变量：

先在 .env.example 对应分区追加条目并附中文注释，保持"模板即文档"的惯例；
分区风格沿用现有的 # ===...=== 区块名 ===...=== 分隔形式；
在代码侧通过 Astro/Vite 提供的环境变量注入通道读取（本页未验证到 src/ 内的读取点，实现时请参考 Astro 官方 import.meta.env 机制）；
若变量含敏感信息，遵循"本地 .env / 平台 Secret"双通道，永不入库。

.env.example — 环境变量模板原文
astro.config.mjs — NODE_ENV 消费点
README.md — 安装、部署与环境变量章节
内容仓库同步与自动构建触发（docs/AUTO_BUILD_TRIGGER.md）：属兄弟页面主题，本页仅引用
站点业务配置（src/config/siteConfig.ts 与 src/config/ 模块）：属兄弟页面主题，本页仅引用

环境变量与 .env 配置

Purpose and Scope

Overview

Architecture

环境变量清单（.env.example 完整解析）

1. 内容仓库配置（代码/内容分离）

2. IndexNow SEO 配置

3. Bilibili 会话数据

4. 框架级变量 NODE_ENV

Configuration Options

核心流程：本地与部署两条配置路线

Usage Examples

本地内容模式（入门推荐）

启用内容分离模式

Failure Modes, Edge Cases & Security

Performance / Operational Notes

Extension Points

Related Links

Sources