博客部署与使用指南

博客部署流程，博客依赖 php、composer、git，部署前需要先安装好环境。

🚀 快速开始

1. 环境准备

确保您的本地环境已安装以下组件：

• PHP ≥ 7.4
• Composer
• Git

安装 PHP、Composer、git：

windows

# windows powershell，管理员权限运行
# 过程中会提示是否修改执行策略，输入 Y 确认。
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex
scoop install php composer git

MacOS

# macOS
brew install php composer git

Ubuntu/Debian

# Ubuntu/Debian  
sudo apt-get install php composer git

2. 克隆项目到本地：

git clone https://hk.gh-proxy.org/https://github.com/Apursuit/the0n3-blog.git
cd the0n3-blog

3. composer 依赖安装

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

composer install

4. 开始写作

博客结构如下:

.
├── assets/      # 前端资源（CSS / JS / Prism 代码高亮）
├── config/      # 站点配置目录
├── logs/        # 构建日志目录（默认追加写入，超过14天自动清空重写）
├── posts/       # Markdown 文章源文件（支持子目录嵌套）
├── public/      # 静态资源（构建时会原样拷贝至 dist/ 根目录）
├── images/      # 图片资源（构建时会原样拷贝至 dist/images/）
├── src/         # 核心 PHP 业务逻辑代码
├── templates/   # HTML 页面模板
├── dist/        # 构建后的最终静态站点输出目录（执行 build 后生成）
└── 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/

5. 推送博客

github 配置 ssh 公钥，参考 https://www.qfxaile.top/index.php/archives/120.html

配置本地 git 仓库，关联远程仓库地址，提交并推送代码到远程仓库。

git init
git add .
git commit -m "first commit"
git remote add origin <远程仓库地址>
git push -u origin main

推送到远程仓库后，GitHub Action 会自动触发构建流程，构建完成后会将 dist 目录下的静态文件推送到 gh-pages 分支，实现自动部署。

Giscus 评论系统（可选）

默认关闭。如需启用，请在 config/site.php 的 giscus 配置中填入你自己的参数（repo / repo_id / category / category_id）。

重要：不要直接使用他人的配置，否则评论会写入对方仓库。

注意：启用 Giscus 评论系统需要在 GitHub 仓库创建 Discussions，具体步骤参考这篇文章 https://www.lixueduan.com/posts/blog/02-add-giscus-comment/