🛠️ 博客模板环境配置与上线指引 (Configuration Guide)

本文档面向博客使用者与站长，提供从源码克隆、脱敏参数替换、第三方服务接入（GA4、AdSense、Giscus 评论）到自动化部署上线的全流程完整配置指南。

一、快速环境检查

本项目推荐 Node.js 与 pnpm 运行环境：

Node.js: >= 20.x (推荐 22.x LTS)
Package Manager: pnpm >= 9.x (项目已绑定 pnpm@10.27.0)

bash

# 安装项目依赖
pnpm install

# 启动本地热重载开发服务器 (默认端口 http://localhost:5600)
pnpm dev

# 运行自动化测试质量门禁
pnpm test

# 生产环境 SSG 构建
pnpm build

二、站点基础信息配置 (`.vitepress/config.ts`)

站点基础元数据、导航栏、搜索与构建规则均收敛在 .vitepress/config.ts 中：

1. 基础元数据与版权

typescript

export default withMermaid(
    defineConfig({
        title: `MagicNote`, // 博客主标题
        description: `Fisher's Blog. Learn to ask questions, good questions are more important than answers`, // 站点描述 (SEO)
        base: '/', // 站点根路径，若部署在子路径下请调整 (如 '/blog/')
        
        themeConfig: {
            logo: '/assets/logo/32.png', // 站点 Logo 路径 (存放于 public/ 目录)
            copyrightUrl: 'https://aicro.net/', // 页脚版权跳转链接
            copyrightName: `AICROSOFT`, // 页脚版权所有人名称
            showFireworksAnimation: true, // 文章列表页是否启用点击烟花特效
            // version: '2.11.0', // 可选覆盖：博客版本号 (默认自动取 package.json 中的 version)
            // vitepressVersion: '1.6.4', // 可选覆盖：VitePress 引擎版本号 (默认自动从 package.json 依赖中动态提取)
            // ...
        }
    })
)

💡 页脚版本号自动解析机制：
博客系统版本 (v{{ version }})：优先读取 themeConfig.version，默认自动读取 package.json 的 version 字段（如 v2.11.0）；
VitePress 引擎版本 (VitePress - {{ vitepressVersion }})：优先读取 themeConfig.vitepressVersion，默认自动从 package.json 的 devDependencies.vitepress 动态提取纯版本号（自动规整 ^ / ~ 等前缀符号），依赖升级时页脚展示与真实版本实时对齐。

2. 导航栏菜单 (`themeConfig.nav`)

typescript

nav: [
    { text: '🏡Home', link: '/' },
    { text: '📚 Category', link: '/pages/category' },
    { text: '📦Archives', link: '/pages/archives' },
    { text: '🔖Tags', link: '/pages/tags' },
    { text: 'ℹ️About', link: '/pages/about' }
]

3. 文章过滤与本地高效调试 (`devFolders` & `excludePostNames`)

当博客积累数千篇文章时，全量热更新可能影响响应速度。系统内置了调试目录隔离机制：

typescript

// 仅用于本地调试时显示的博文目录 (可通过注释切换调试范围)
const devFolders = ['posts/draft/**/**.md', 'posts/2026/**/**.md']

// 生产构建时强制排除的私密或垃圾箱目录
const excludePostNames = ['2011', 'trash', 'draft', 'private']

// 每页渲染文章数量 (默认 11 篇)
const pageSize = 11

三、第三方数据分析与变现广告配置 (脱敏替换)

为确保开源纯净度，模板中的商业运营凭证均已进行脱敏处理。在正式上线前，请替换为你个人的真实 ID。

1. Google Analytics 4 (GA4) 流量统计

配置位置：.vitepress/config.ts 中的 head 数组
脱敏占位符：G-XXXXXXXXXX

代码结构：

typescript

head: [
    // Google Analytics 4 (GA4)
    [
        'script',
        {
            async: '',
            src: 'https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX'
        }
    ],
    [
        'script',
        {},
        `window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-XXXXXXXXXX');`
    ],
    // ...
]

获取与配置方法：
1. 登录 Google Analytics 控制台；
2. 进入「管理」 $\to$「数据流 (Data Streams)」 $\to$ 选择或创建「网站」数据流；
3. 复制以 G- 开头的「衡量 ID (Measurement ID)」；
4. 将 .vitepress/config.ts 中的两处 G-XXXXXXXXXX 替换为你的真实 ID；
5. 若无需启用 GA4，直接删除或注释上述两个 script 节点即可。

配置位置：.vitepress/config.ts 中的 head 数组
脱敏占位符：ca-pub-XXXXXXXXXXXXXXXX

代码结构：

typescript

head: [
    // ...
    // Google AdSense
    [
        'script',
        {
            async: '',
            src: 'https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-XXXXXXXXXXXXXXXX',
            crossorigin: 'anonymous'
        }
    ]
]

获取与配置方法：
1. 登录 Google AdSense 控制台；
2. 进入「网站」 $\to$ 添加你的博客独立域名；
3. 获取你的 AdSense 客户 ID（以 ca-pub- 开头，共 16 位数字）；
4. 将 .vitepress/config.ts 中的 ca-pub-XXXXXXXXXXXXXXXX 替换为你的客户 ID；
5. 若未申请或无需广告变现，直接删除或注释该节点。

四、 Giscus 评论系统配置 (`CommentGiscus.vue`)

本博客深度集成基于 GitHub Discussions 的无服务器开源评论系统 Giscus。

组件文件：.vitepress/theme/components/CommentGiscus.vue
脱敏占位符：
- repo: 'your-username/your-repo-name'
- repoId: 'YOUR_REPO_ID'
- categoryId: 'YOUR_CATEGORY_ID'

组件配置片段

html

<script setup lang="ts">
import Giscus from '@giscus/vue'
import { useData } from 'vitepress'

const { isDark } = useData()
</script>

<template>
  <div class="giscus-wrapper">
    <Giscus
      repo="your-username/your-repo-name"
      repo-id="YOUR_REPO_ID"
      category="General"
      category-id="YOUR_CATEGORY_ID"
      mapping="pathname"
      reactions-enabled="1"
      emit-metadata="0"
      input-position="top"
      :theme="isDark ? 'dark' : 'light'"
      lang="zh-CN"
      loading="lazy"
    />
  </div>
</template>

完整开通与配置步骤：

GitHub 仓库准备：
- 确保你的博客源码仓库（或专门用于存放评论的仓库）为 公开 (Public) 仓库；
- 访问 GitHub 仓库主页 $\to$ 点击 Settings $\to$ 在 Features 区域中勾选开启 Discussions。
安装 Giscus GitHub App：
- 访问 GitHub Apps - Giscus；
- 点击 Install，并授权访问你的目标仓库。
获取参数配置：
- 打开 giscus.app；
- 在仓库栏目输入 用户名/仓库名，点击验证仓库权限；
- 在 讨论分类 (Discussion Category) 栏目中选择分类（推荐 General 或 Announcements）；
- 页面下方将自动生成 data-repo-id 与 data-category-id 字符串（形如 R_kgDO... 与 DIC_kwDO...）；
填入组件：
- 将上述取值分别填入 CommentGiscus.vue 的 repoId 与 categoryId 中；
- 此时在任何博文正文底部，均可直接加载读者评论并与 GitHub Discussions 实时双向同步。

五、博文排版与增强功能实战

1. FrontMatter 标准规范

markdown

---
title: "我的第一篇技术架构博文"
date: "2026-10-05 14:30"
category: "架构设计"
tags:
  - "Vue"
  - "VitePress"
order: 10 # 置顶权重，大于 0 则置顶并显示 📌 图钉，数值越大越靠前
description: |-
  文章摘要支持原生 Markdown 富文本语法！
  支持相对路径图片：![架构图](./images/arch.svg)
  正文详情页会自动检测摘要图片并隐去重复摘要，首页列表则正常渲染！
---

# 博文正文标题
...

2. 插图全屏灯箱放大

正文与摘要中的任何图片，系统均已自动注入 medium-zoom 支持。读者在桌面端或移动端点击任意插图，即可平滑全屏放大，点击背景或滚动即可退出。

3. Mermaid 架构图绘制

系统内置 vitepress-plugin-mermaid，无需安装任何客户端工具，直接在 Markdown 中编写时序图、流程图与类图：

markdown

```mermaid
flowchart LR
    A[编写 Markdown] --> B[pnpm build: SSG 编译]
    B --> C[CI/CD 自动化脱敏清洗]
    C --> D[部署至 Cloudflare Pages / GitHub Pages]
```

六、部署发布指南

1. 演示站与正式站双轨部署

开源演示站 (blogdemo): https://blogdemo.aicro.net/
- 基于脱敏后的纯净开源工程自动化部署；
- 自动将发布文档、配置说明注入至博文中展示。
正式全功能站 (Production): https://blog.aicro.net/
- 包含站长全量文章与互动评论。

2. Cloudflare Pages 静态部署

在 Cloudflare 控制台新建 Pages 项目；
构建配置：
- Framework Preset: None / VitePress
- Build Command: pnpm build
- Build Output Directory: .vitepress/dist
- Node.js Version: 20 或 22 (环境变量 NODE_VERSION: 22.0.0)
绑定自定义域名并开启 HTTPS。

3. GitHub 同步流水线

在 Azure DevOps 中运行 blog.github-sync.cd.yml 流水线时：

目标同步分支已升级为 dev/v<两位版本号> 规范（当前为 dev/v2.11）；
自动完成脱敏清洗、测试编译、Cloudflare Pages 预发布巡检、人工审批门禁以及安全推送到 GitHub。

一、 快速环境检查 ​

二、 站点基础信息配置 (.vitepress/config.ts) ​

1. 基础元数据与版权 ​

2. 导航栏菜单 (themeConfig.nav) ​

3. 文章过滤与本地高效调试 (devFolders & excludePostNames) ​

三、 第三方数据分析与变现广告配置 (脱敏替换) ​

1. Google Analytics 4 (GA4) 流量统计 ​

2. Google AdSense 网页广告 ​

四、 Giscus 评论系统配置 (CommentGiscus.vue) ​

组件配置片段 ​

完整开通与配置步骤： ​

五、 博文排版与增强功能实战 ​

1. FrontMatter 标准规范 ​

2. 插图全屏灯箱放大 ​

3. Mermaid 架构图绘制 ​

六、 部署发布指南 ​

1. 演示站与正式站双轨部署 ​

2. Cloudflare Pages 静态部署 ​

3. GitHub 同步流水线 ​

一、快速环境检查

二、站点基础信息配置 (`.vitepress/config.ts`)

1. 基础元数据与版权

2. 导航栏菜单 (`themeConfig.nav`)

3. 文章过滤与本地高效调试 (`devFolders` & `excludePostNames`)

三、第三方数据分析与变现广告配置 (脱敏替换)

1. Google Analytics 4 (GA4) 流量统计

2. Google AdSense 网页广告

四、 Giscus 评论系统配置 (`CommentGiscus.vue`)

组件配置片段

完整开通与配置步骤：

五、博文排版与增强功能实战

1. FrontMatter 标准规范

2. 插图全屏灯箱放大

3. Mermaid 架构图绘制

六、部署发布指南

1. 演示站与正式站双轨部署

2. Cloudflare Pages 静态部署

3. GitHub 同步流水线