# PureStatic

**Repository Path**: itlong/pure-static

## Basic Information

- **Project Name**: PureStatic
- **Description**: 在后台一键把前台页面落成真实 HTML：支持首页（含分页 page_N.html）、分类页（含分页）和已公开文章页（如 post/13.html），按站点当前伪静态规则生成对应路径，地址含目录时自动创建目录。生成时优先在服务端直接渲染页面，渲染结果异常会自动回退 HTTP 抓取；文章按每批 20 篇分批执行，避免超时。所有生成文件会记录清单，可一键清空（只删静态文件，不影响文章数据）。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-09
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 内容纯静态（PureStatic）

把 Z-BlogPHP 的前台页面落成真实 HTML 文件，按站点当前的伪静态规则写到对应路径。生成后由 Web 服务器直接命中静态文件，减少 PHP 与数据库开销。

- 插件 ID：PureStatic
- 版本：1.0
- 适用：Z-BlogPHP
- 建议环境：PHP 5.6 及以上（代码使用闭包），目录可写

## 功能

- 生成首页：第 1 页写 `index.html`，后续分页按规则生成（如 `page_2.html`）。
- 生成分类页：按分类的真实访问地址生成，含分；地址含目录时自动创建目录。
- 生成文章页：只处理已公开文章（`log_Type=0`、`log_Status=0`），如 `post/13.html`。
- 全量生成：先生成首页与全部分类，再分批生成文章；首页或分类失败则停止，不继续生成文章。
- 分批执行：每批默认 20 篇（可配置，范围 1–50），自动提交下一批，直到不足一批为止。
- 一键清空：删除本插件生成过的静态文件，并清理产生的空目录，不影响文章数据。

## 安装

1. 把 `PureStatic` 目录放到 `zb_users/plugin/` 下。
2. 后台「插件管理」中启用「内容纯静态」。
3. 启用后后台顶部出现「内容纯静态」菜单（仅站长可见）。

> 卸载插件不会自动删除已生成的 HTML，如需清理请先使用「清空静态文件」。

## 使用

进入后台「内容纯静态」页面，按需点击：

| 操作 | 说明 |
| --- | --- |
| 开始全量生成 | 首页 + 全部分类 + 分批生成全部公开文章 |
| 只生成首页 | 生成首页及其分页 |
| 只生成分类 | 生成所有分类及其分页 |
| 只生成文章 | 从第一批开始生成文章，可自动续跑 |
| 清空静态文件 | 删除已生成的静态文件（会二次确认） |

执行结果会以日志形式列出落盘的相对路径，失败项标红并给出原因（如「无法创建目录」「抓取失败 HTTP 404」「文章不存在或未公开」）。

## 生成规则

- 取页面：优先在服务端直接渲染（`ViewList` / `ViewPost` 输出缓冲），渲染结果异常时自动回退 HTTP 抓取（跟随跳转，超时 20 秒）。
- 有效性校验：长度不足 100 字节、或不含 `<html` / `<!doctype` 的响应视为无效。
- 路径映射：去掉站点 host 后按 URL 路径落盘；以目录结尾的地址补 `index.html`；`index.php` 映射为 `index.html`。
- 安全限制：含 `..`、盘符或指向 `zb_system/` `zb_users/` 的路径一律拒绝写入。
- 写入方式：递归创建目录（0755），先写 `.tmp` 再 `rename` 覆盖，避免生成半截文件。
- 分页与数量：按后台「每页显示数量」计算页数，分类统计会包含子分类（取决于是否开启显示子分类文章）。

## 配置

每批文章数量保存在插件配置项的 `batch` 中（安装时默认写入 20，未内置配置界面，如需调整请直接修改配置值）：

```ini
batch = 20
```

取值范围 1–50，配置缺失或非法时回退为 20。

## 让静态文件生效

生成 HTML 后，需要在 Web 服务器上让请求优先命中静态文件，未命中再回落到 PHP。

Nginx：

```nginx
location / {
    try_files $uri $uri/ /index.php?$args;
}
```

Apache（`.htaccess`）：

```apache
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
```

## 注意事项

- 需要 Web 运行用户对站点根目录（及 `post/` 等子目录）有写权限。
- 文章内容、模板、侧栏等变更后，静态文件不会自动更新，需要重新生成。
- 「清空静态文件」除按生成清单删除外，还会扫描根目录下的 `index.html`、`page_*.html`、`category-*.html` 以及 `post/*.html` 一并删除；如这些路径下有非本插件产生的同名文件，请先确认。
- 生成期间不要关闭页面；分批任务通过自动提交继续，中途失败会停止自动续跑。

## 文件说明

- `include.php`：插件注册、后台菜单与全部生成逻辑。
- `main.php`：后台操作页面与结果展示。
- `plugin.xml`：插件信息与简介。
- `logo.png`：插件图标。