kaiwen.work Typecho 网站架构分析报告

创建时间：2026-04-24
用途：作为后续长期维护和建设的基础参考文档
项目路径：/Users/xuekaiwen/Documents/Github/kaiwen.work

1. 项目基本信息

2. 入口文件

前台核心流程（index.php）：

require config.inc.php
    → \Widget\Init::alloc()
    → \Typecho\Plugin::factory('index.php')->begin()
    → \Typecho\Router::dispatch()
    → \Typecho\Plugin::factory('index.php')->end()

3. 目录职责总览

核心维护原则：所有改动只在 /usr/ 下进行；/var/ 和 /admin/ 升级时会被覆盖。

4. 核心框架（/var/Typecho/）关键类

数据库层支持：MySQL / PostgreSQL / SQLite，三种各有 PDO 和原生适配器。

5. 业务 Widget（/var/Widget/）关键类

• 数据基类（/var/Widget/Base/）：Contents、Comments、Metas、Options、Users
• 内容相关（/var/Widget/Contents/）：Post/、Page/、Attachment/、Related/
• 元数据相关（/var/Widget/Metas/）：Category/、Tag/
• 评论相关（/var/Widget/Comments/）：Admin、Archive、Edit、Ping、Recent
• 其他重要：Archive（前台文章展示）、Options（全局选项）、User（当前用户）、Init（系统初始化）、Login / Logout / Register、Action（后台操作基类）、Upload、Backup、Stat、XmlRpc、Feed

6. 数据库表结构（前缀 typecho_）

SQL 定义见 install/SQLite.sql。

7. 主题系统（/usr/themes/）

当前已安装主题

标准模板文件

theme/
├── index.php         # 首页（文章列表）
├── post.php          # 单篇文章
├── page.php          # 独立页面
├── archive.php       # 归档列表
├── search.php        # 搜索结果
├── 404.php           # 错误页
├── comments.php      # 评论区块
├── header.php        # 头部（通用）
├── footer.php        # 底部（通用）
├── sidebar.php       # 侧边栏（可选）
├── functions.php     # 主题函数与配置
└── *.css / img/      # 静态资源

主题开发要点

• 配置入口：在 functions.php 中定义 themeConfig(Typecho\Widget\Helper\Form $form)，即可在后台"外观 > 设置外观"中看到配置项

• 模板写法：

  • 引入模板片段：$this->need('header.php');
  • 遍历文章：while ($this->next()) { ... }
  • 取全局配置：Typecho\Widget::widget('Widget\Options')->title
  • 取文章字段：$this->title、$this->content、$this->permalink、$this->date->format('Y-m-d')

8. 插件系统（/usr/plugins/）

当前插件

• HelloWorld/（示例插件，仅含 Plugin.php）

插件模板

<?php
namespace TypechoPlugin\YourPluginName;

use Typecho\Plugin\PluginInterface;
use Typecho\Widget\Helper\Form;

class Plugin implements PluginInterface
{
    public static function activate() { /* 激活时执行，可注册钩子 */ }
    public static function deactivate() { /* 禁用时执行 */ }
    public static function config(Form $form) { /* 全局配置面板 */ }
    public static function personalConfig(Form $form) { /* 个人配置面板 */ }
}

钩子机制

• 注册：\Typecho\Plugin::factory('Widget\Archive')->footer = __CLASS__ . '::methodName';
• 触发点分布在 Widget 和模板中（如 index.php 中的 begin / end）
• 插件配置读取：Typecho\Widget::widget('Widget\Options')->plugin('YourPluginName')->key

9. 敏感文件（未入 Git）

以下文件需要在部署时手工配置或备份：

• config.inc.php（数据库连接、盐值）
• SQLite 数据库文件（路径由 config.inc.php 指定）
• usr/uploads/（用户上传的媒体文件，如果存在）

10. 后续维护规范

1. 功能扩展 → 插件：在 usr/plugins/ 新建独立目录，不要改 /var/ 下任何文件

2. 外观/布局调整 → 主题：

   • 小改动：直接在 classic-22 或 default 上改
   • 大改动：建议复制为新主题目录（如 kaiwen-custom/）再改，避免后续升级冲突
3. 数据库操作：统一走 Typecho\Db 和 Widget 抽象，不要在模板里写裸 SQL
4. 敏感信息：任何涉及密钥、密码、路径的内容不要入 Git
5. 变更记录：每次维护在 .maintenance/ 目录追加记录文档（如 02-xxx-change.md）
6. 升级 Typecho 核心：只需替换 /var/、/admin/、/install/ 三个目录 + index.php / install.php，/usr/ 保持不动

11. 常用 Widget 调用速查

// 全局配置
$options = Typecho\Widget::widget('Widget\Options');
echo $options->title, $options->description, $options->siteUrl;

// 当前用户
$user = Typecho\Widget::widget('Widget\User');
if ($user->hasLogin()) { echo $user->screenName; }

// 最近文章
Typecho\Widget::widget('Widget\Contents\Post\Recent')->to($posts);
while ($posts->next()) { echo $posts->title; }

// 分类树
Typecho\Widget::widget('Widget\Metas\Category\List')->listCategories();

// 插件配置
$cfg = Typecho\Widget::widget('Widget\Options')->plugin('PluginName');

本文档将随项目维护同步更新。