博客部署与使用指南（Windows）

博客部署流程

博客依赖 php环境

00. PHP安装

下载地址 https://downloads.php.net/~windows/releases/archives/

选择 php-8.5.0-Win32-vs17-x64.zip

下载后，解压压缩包到指定目录，这里演示解压到 C:\php-8.5.4，你可以解压到任何目录，如 D:\php-8.5.4 等。

01. 环境变量配置

按 win 键，输入环境变量，选择 编辑系统环境变量

选中用户的 Path 变量，点击编辑，点击新建，输入 php 的解压目录，例如 C:\php-8.5.4\，点击确定保存。

验证是否成功，打开终端（按 win 键输入终端或cmd），输入 php -v，如果显示 PHP 版本信息，则说明配置成功。

php 需要启用 zip 扩展，打开 php.ini 文件（在 php 解压目录下），找到 extension=zip，去掉前面的分号 ; 以启用该扩展，保存文件。

02. composer 安装

下载地址：https://getcomposer.org/download/

下载后，运行安装程序，选择安装路径（可以放在任意目录），点击安装.

composer 安装过程会检测你的 PHP 环境，如果之前的环境变量配置正确，安装程序会自动找到 PHP 可执行文件。

不使用代理，留空，点击继续，后续默认完成安装。

打开终端，输入 composer ，如果显示 composer 相关帮助信息，则说明安装成功。

03. composer 依赖安装

在博客根目录下，打开终端，输入以下命令安装依赖：

composer install

04. 博客文章

博客结构如下：

• assets/ 前端资源（CSS/JS/Prism）
• config/ 站点配置
• logs/ 构建日志
• posts/ Markdown 文章（支持子目录）
• public/ 静态资源（原样拷贝到 dist/）
• images/ 图片资源（原样拷贝到 dist/images/）
• src/ 核心 PHP 逻辑（解析、渲染、生成）
• templates/ 页面模板
• dist/ 构建输出（生成后出现）
• main.php CLI 入口

其中，posts/ 目录下存放 Markdown 文章，可以直接在该目录下创建 Markdown 文件，也可以创建子目录来组织文章，例如 posts/2026/03/22/test.md。

Markdown 文章需要包含 YAML Front Matter，格式如下：

title: Hello World
date: 2026-03-20
permalink: /posts/hello-world/
tags:
    - 示例
categories:
    - 示例
pin: 0
draft: false
sidebar: true

可以通过运行 main.php 获取新文章模板：

php main.php new "文章标题"

这会打印一份包含 Front Matter 模板的 Markdown 内容，你可以复制到新的 Markdown 文件中，并根据需要修改字段值。

注意，--- 分隔符必须顶格、并且必须出现在文件开头

如果文章包含图片资源，可以放在 images 目录下，例如 images/testdir/1.png，然后在 Markdown 中使用相对路径引用：

![测试图片](/images/testdir/1.png)

文章书写完成后，运行构建命令：

php main.php build

博客构建的产物在 dist目录，开启 web 服务，访问 http://localhost:8000 预览效果：

php -S localhost:8000 -t dist/