TypechoBio 个人主页插件

支持指定域名，复用Typecho的评论系统，并指定评论文章ID。

安装方式

方式一：AB-Store 一键安装（推荐）

安装 AdminBeautify 插件后，进入后台 AB-Store 应用商店，搜索 TypechoBio 即可一键安装并获取后续更新。

方式二：手动安装

下载最新 Release 压缩包
解压为 TypechoBio 文件夹
上传至 Typecho 的 usr/plugins/ 目录
登录后台 → 控制台 → 插件管理 → 启用 TypechoBio

方式三：Git 克隆

cd /path/to/typecho/usr/plugins/
git clone https://github.com/lhl77/TypechoBio.git TypechoBio

可安装主题

Imsyy	Duckfolio	Zyyo

Dmego	Wexuo	IAMI

TypechoBio 主题适配文档

本文面向 TypechoBio 主题开发者，目标是把“一个现成前端页面或主题源码”稳定适配到 TypechoBio。

文档内容基于当前插件实现整理，和实际代码行为对齐，适用于以下场景：

新增一个本地主题到 usr/plugins/TypechoBio/templates/<theme>/
将外部 HTML、静态站点、Vite 构建产物、主题源码迁移到 TypechoBio
为主题接入插件统一的配置系统、评论区、独立域名运行时上下文
为主题打包成远程主题市场可安装的 zip 包

1. 运行模型

TypechoBio 不是 Typecho 前台主题，而是“独立域名命中后接管输出”的插件入口。

当前请求命中插件后，执行链路大致如下：

插件根据 bio_hosts 判断当前 Host 是否需要被 TypechoBio 接管。
若命中，则先处理主题专属 API，再处理主题静态资源请求。
非资源请求会进入 usr/plugins/TypechoBio/templates/index.php。
templates/index.php 读取当前启用主题、主题配置、用户状态、评论数据等上下文。
最终 require usr/plugins/TypechoBio/templates/<theme>/home.php 输出完整页面。

这意味着：

home.php 需要自己输出完整 HTML 页面，不要假设 Typecho 默认前台模板会包裹你。
主题运行时可直接访问数据库、登录态、插件配置，但应优先使用插件已整理好的 $typechoBioContext。
资源、评论、配置都应按 TypechoBio 的约定来接，而不是直接照搬原主题的 CMS 假设。

2. 主题最小目录结构

一个主题至少要满足下面的目录结构，才能被 TypechoBio 识别：

usr/plugins/TypechoBio/
└── templates/
    └── my-theme/
        ├── home.php
        ├── theme.json
        ├── assets/
        │   ├── app.css
        │   └── app.js
        ├── images/
        └── ...

识别规则很严格：

templates/<dir>/home.php 必须存在
templates/<dir>/theme.json 必须存在
两者缺一不可，否则 discoverThemes() 不会把这个目录识别为可用主题

建议：

主题目录名只使用字母、数字、下划线、连字符
目录名与 theme.json 中的主题标识保持一致
把当前主题的静态资源全部放在本主题目录下，不要散落到插件根目录

3. home.php 的职责

home.php 是主题真正的入口文件，建议把它当成“页面壳层模板”。它至少应负责：

输出完整 HTML 文档结构
读取 $typechoBioContext
根据 themeConfig 渲染页面内容
正确引用当前主题静态资源
按需接入评论区、代理接口、额外共享片段

一个最小可运行的例子如下：

<?php
if (!defined('__TYPECHO_ROOT_DIR__')) {
    exit;
}

$ctx = isset($typechoBioContext) && is_array($typechoBioContext)
    ? $typechoBioContext
    : array();

$themeConfig = isset($ctx['themeConfig']) && is_array($ctx['themeConfig'])
    ? $ctx['themeConfig']
    : array();

$siteTitle = isset($ctx['siteTitle']) ? (string) $ctx['siteTitle'] : 'TypechoBio';
$themeAssetBase = isset($ctx['themeAssetBase']) ? (string) $ctx['themeAssetBase'] : '';
$pluginRoot = dirname(dirname(__DIR__));
?>
<!doctype html>
<html lang="zh-CN">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title><?php echo htmlspecialchars($siteTitle, ENT_QUOTES, 'UTF-8'); ?></title>
    <link rel="stylesheet" href="<?php echo htmlspecialchars($themeAssetBase . 'assets/app.css', ENT_QUOTES, 'UTF-8'); ?>">
</head>
<body>
    <main>
        <h1><?php echo htmlspecialchars($siteTitle, ENT_QUOTES, 'UTF-8'); ?></h1>
    </main>

    <?php
    $bioCommentOptions = array(
        'enabled' => true,
        'container_class' => 'my-theme-comments',
    );
    require $pluginRoot . '/views/comment-section.php';
    require $pluginRoot . '/views/comment-script.php';
    ?>

    <script src="<?php echo htmlspecialchars($themeAssetBase . 'assets/app.js', ENT_QUOTES, 'UTF-8'); ?>"></script>
</body>
</html>

4. 运行时上下文 `$typechoBioContext`

templates/index.php 在载入 home.php 前，会把通用运行时信息整理到 $typechoBioContext 中。主题应优先从这里取值，而不是自己重新拼一遍。

当前常用字段如下。

4.1 基础站点信息

host：当前命中的域名
siteTitle：站点标题
siteUrl：站点地址
adminUrl：后台地址
siteIcon：插件设置中的站点图标

4.2 用户信息

userLogged：当前是否已登录
userName：登录用户名
userGroup：用户组

4.3 主题与插件信息

themeKey：当前主题目录名
themeConfig：当前主题解析后的配置数组
themeAssetBase：当前主题静态资源基址
pluginAssetBase：插件根资源基址
pluginName
pluginVersion
pluginLink

4.4 评论与接口信息

profileApi：登录态查询接口
commentApi：评论提交接口
commentTarget：评论目标文章信息
commentList：已审核评论列表
commentResult
commentMessage

4.5 其他常用数据

posts：最近文章列表，当前实现默认取最近 10 篇已发布文章
headPreMeta：后台配置的自定义 head 片段（meta 前置）
headCustomCss：后台配置的自定义 CSS
headCustomJs：后台配置的自定义 JS
loadStart：请求开始时间

4.6 读取示例

<?php
$ctx = $typechoBioContext;
$config = isset($ctx['themeConfig']) ? $ctx['themeConfig'] : array();
$title = isset($ctx['siteTitle']) ? $ctx['siteTitle'] : '';
$logged = !empty($ctx['userLogged']);
$commentApi = isset($ctx['commentApi']) ? $ctx['commentApi'] : '';

5. theme.json 规范

theme.json 是 TypechoBio 识别主题元数据和配置表单的唯一标准文件。

一个推荐的完整示例如下：

{
  "name": "My Theme",
  "version": "1.0.0",
  "description": "一个适配到 TypechoBio 的主题",
  "fields": [
    {
      "key": "hero_title",
      "label": "首屏标题",
      "type": "text",
      "default": "Hello TypechoBio",
      "description": "显示在首屏的大标题"
    },
    {
      "key": "hero_desc",
      "label": "首屏描述",
      "type": "textarea",
      "default": "这是主题说明",
      "description": "支持多行文本"
    },
    {
      "key": "theme_mode",
      "label": "配色模式",
      "type": "select",
      "default": "system",
      "description": "主题初始配色模式",
      "options": {
        "light": "浅色",
        "dark": "深色",
        "system": "跟随系统"
      }
    },
    {
      "key": "show_comments",
      "label": "启用评论区",
      "type": "checkbox",
      "default": "1",
      "description": "关闭后不渲染评论区"
    }
  ]
}

5.1 顶层字段

name：主题显示名称
version：主题版本号，主题市场比较更新时会用到
description：主题简介
fields：配置字段数组

5.2 fields 数组支持的字段

每个字段对象支持：

key：字段键名，必填，只允许字母、数字、下划线
label：后台显示名称
type：字段类型
default：默认值
description：后台说明文字
options：仅 select 类型使用

当前插件支持的 type 只有以下五种：

text
textarea
number
select
checkbox

注意事项：

key 不能包含空格、连字符、点号、斜杠
不支持对象嵌套配置结构，复杂数据请序列化成字符串或 JSON 字符串
checkbox 最终会被规范化为字符串 1 或 0
select 的 options 必须是对象，键是实际值，值是后台显示文本

5.3 默认值行为

TypechoBio 会根据 theme.json 自动做以下同步：

新增字段时，自动把默认值补进配置 JSON
删除字段时，自动从配置 JSON 和后台表单中移除
新安装主题时，当前页会把该主题默认配置直接同步到主题配置 JSON

因此，default 字段应认真填写，不要省略，否则该字段首次接入时会是空字符串。

6. 配置系统是怎么存的

TypechoBio 当前同时维护两层配置表示，但开发时应把 JSON 当成最终结构：

统一 JSON：bio_theme_configs_json
后台表单字段：bio_theme_cfg__{theme}__{key}

说明：

配置页展示的是常规表单项
表单提交时会自动同步回 bio_theme_configs_json
插件内部也会在主题增删字段时自动做规范化同步

主题开发者应遵守：

在 home.php 中优先读取 $typechoBioContext['themeConfig']
不要自己拼接 bio_theme_cfg__... 去数据库取值
复杂数组、列表、对象数据建议直接存在 text 或 textarea 字段里，再在主题内自己 json_decode

例如：

<?php
$config = isset($typechoBioContext['themeConfig']) ? $typechoBioContext['themeConfig'] : array();
$socialLinks = array();
if (!empty($config['social_links'])) {
    $decoded = json_decode((string) $config['social_links'], true);
    if (is_array($decoded)) {
        $socialLinks = $decoded;
    }
}

7. 静态资源接入规范

TypechoBio 会拦截当前Typecho前台主题的资源请求，并直接从当前启用TypechoBio主题目录回源。

7.1 推荐写法

最稳妥的写法是始终使用 $typechoBioContext['themeAssetBase'] 来拼资源路径：

<link rel="stylesheet" href="<?php echo htmlspecialchars($typechoBioContext['themeAssetBase'] . 'assets/app.css', ENT_QUOTES, 'UTF-8'); ?>">
<script src="<?php echo htmlspecialchars($typechoBioContext['themeAssetBase'] . 'assets/app.js', ENT_QUOTES, 'UTF-8'); ?>"></script>
<img src="<?php echo htmlspecialchars($typechoBioContext['themeAssetBase'] . 'images/avatar.png', ENT_QUOTES, 'UTF-8'); ?>" alt="avatar">

7.2 资源放置建议

建议把资源全部收敛到主题目录内部，例如：

templates/my-theme/
├── home.php
├── theme.json
├── assets/
├── css/
├── js/
├── images/
├── img/
└── font/

7.3 根路径资源的兼容

插件当前会对以下请求做主题目录回源：

当前主题目录下的普通请求路径
/assets/...
/favicon.ico
/apple-touch-icon.png
/robots.txt

这意味着某些原主题若大量引用根路径资源，例如 /assets/app.css，在当前启用主题下通常也能被命中。

但仍建议在适配时主动改成基于 themeAssetBase 的显式路径，原因是：

路径更清晰
不依赖隐式兼容逻辑
方便后续迁移、调试和主题切换

7.4 大小写问题

Linux 文件系统区分大小写，资源路径必须和真实文件名完全一致。

不要把：

Pacifico-Regular.ttf 写成 pacifico-regular.ttf
Images/avatar.png 写成 images/avatar.png

CSS 中的相对路径也一样需要严格匹配真实目录大小写。

7.5 MIME 类型

插件已经对常见资源做了固定 MIME 映射，包括：

css
js / mjs
json / map
svg
ico
png / jpg / webp / avif
woff / woff2 / ttf / otf / eot

所以主题构建产物可以直接放进主题目录，不必额外再配静态服务器。

8. 评论区接入

TypechoBio 已提供统一的评论区渲染片段，主题适配时优先复用，不建议每个主题自己重复造一套评论后端。

8.1 接入前提

后台插件配置中必须填写：

评论文章 ID，即 bio_comment_cid

未填写时，共享评论组件会输出“尚未配置评论文章 ID”的提示。

8.2 最小接入方式

在主题 home.php 中加入：

<?php
$pluginRoot = dirname(dirname(__DIR__));
$config = isset($typechoBioContext['themeConfig']) ? $typechoBioContext['themeConfig'] : array();
$showComments = !isset($config['show_comments']) || in_array((string) $config['show_comments'], array('1', 'true', 'on', 'yes'), true);

$bioCommentOptions = array(
    'enabled' => $showComments,
    'container_tag' => 'section',
    'container_class' => 'my-theme-comment-section',
    'id' => 'bio-comments',
    'title' => '留言板',
    'title_tag' => 'h3',
    'reload_on_success' => true,
    'reload_delay' => 500,
);

require $pluginRoot . '/views/comment-section.php';
require $pluginRoot . '/views/comment-script.php';

8.3 可用选项

$bioCommentOptions 当前支持：

enabled
container_tag
container_class
id
title
title_tag
reload_on_success
reload_delay
target_missing_text
empty_list_text

8.4 共享类名

共享评论模板会输出以下类名，主题只需给这些类写样式：

.bio-comment-heading
.bio-comment-status
.bio-comment-form
.bio-comment-form-row
.bio-comment-field
.bio-comment-actions
.bio-comment-submit
.bio-comment-tip
.bio-comment-list
.bio-comment-item
.bio-comment-meta
.bio-comment-author
.bio-comment-time
.bio-comment-reply-label
.bio-comment-replyto
.bio-comment-text
.bio-comment-children
.bio-comment-empty

8.5 主题侧建议

评论样式建议遵守当前项目已有方向：

突出用户名
弱化发布时间
强调正文内容
嵌套回复层级要可读，不要只靠细线缩进

9. 远程主题仓库与 zip 包要求

如果你的主题要进入 TypechoBio 后台的“获取主题”市场，需要同时准备：

可安装的 zip 包
远程 themes.json 目录条目

9.1 zip 包要求

插件安装时会：

下载 zip 包
解压到临时目录
在解压结果中查找合法主题目录
合法主题目录必须同时包含 home.php 和 theme.json
成功后复制到 usr/plugins/TypechoBio/templates/<dir>/

因此，zip 包内建议是这样的结构：

my-theme.zip
└── my-theme/
    ├── home.php
    ├── theme.json
    ├── assets/
    └── ...

不建议把一堆文件直接散在 zip 根目录。

9.2 themes.json 条目建议

目录结构建议为：

{
  "schema_version": 1,
  "themes": [
    {
      "dir": "my-theme",
      "name": "My Theme",
      "description": "主题简介",
      "version": "1.0.0",
      "cover": "https://example.com/cover.jpg",
      "zip_url": "https://example.com/my-theme.zip",
      "github_url": "https://github.com/example/my-theme",
      "demo_url": "https://demo.example.com"
    }
  ]
}

字段说明：

dir：本地安装目录名
name：显示名称
description：介绍
version：远程版本号
cover：封面图
zip_url：zip 下载链接
github_url：源码仓库或介绍页
demo_url：在线演示

建议保证：

dir 与 zip 内主题目录名一致
version 与 theme.json 中的 version 一致
cover、zip_url 使用稳定可访问地址

10. 从现成前端项目迁移时的建议流程

如果你是从一个已有 HTML / Vue / React / 静态主题迁移到 TypechoBio，建议按下面顺序做：

第一步：先跑起来页面壳层

把最终可部署 HTML 结构放进 home.php
把 CSS / JS / 字体 / 图片放进主题目录
先确保在 TypechoBio 独立域名下能正常打开页面

第二步：再接插件上下文

把站点标题替换成 $typechoBioContext['siteTitle']
把社交、导航、介绍等可变内容改为 themeConfig
把原硬编码资源路径改成 themeAssetBase

第三步：再接后台可配置字段

在 theme.json 里声明字段
进入插件配置页确认字段能显示
切换到该主题时确认配置项能显示
修改字段并保存，确认 home.php 中能读到新值

第四步：最后再接评论和 API

如需评论区，先配置 show_comments 再引入共享评论片段
如需远程接口，优先做同源代理，不要让浏览器直连不稳定第三方

11. 常见坑与排查

11.1 主题不显示在后台“启用主题”里

优先检查：

templates/<theme>/home.php 是否存在
templates/<theme>/theme.json 是否存在
theme.json 是否是合法 JSON

11.2 主题显示了，但配置项不出现

优先检查：

theme.json 顶层是否有 fields
fields 是否是数组
每个字段是否都带合法 key
key 是否只包含字母、数字、下划线

11.3 默认值没有生效

优先检查：

字段是否写了 default
checkbox 默认值是否写成 1 或 0
复杂 JSON 字符串默认值是否本身就是合法 JSON

11.4 资源 404

优先检查：

路径是否基于 themeAssetBase
文件名大小写是否和真实文件一致
CSS 内相对路径是否正确
资源是否真的放在当前启用主题目录里

11.5 评论区不显示

优先检查：

插件设置里是否填写了 评论文章 ID
主题配置里是否把 show_comments 关掉了
home.php 是否真的 require 了 views/comment-section.php 和 views/comment-script.php

11.6 主题依赖第三方 API，页面打开就报错

优先检查：

是否仍在浏览器直连跨域 API
上游是否有 TLS / 证书 / 频控问题
是否应该改为插件本地代理
代理失败时是否提供了同形 fallback 数据

12. 推荐的适配清单

一个新主题适配完成前，至少逐项确认以下内容：

主题目录下同时存在 home.php 和 theme.json
页面在独立域名下能正常打开
静态资源全部命中
后台能识别并显示主题
后台能切换到该主题
主题配置项能显示
默认值能正确进入 themeConfig
修改配置后前台能读取到新值
评论区可按主题配置开关
若有第三方 API，则已改为同源代理或有降级方案
zip 包安装后，当前页无需手动刷新也能看到配置项与默认值

13. 建议的目录模板

可直接参考下面这个目录组织：

templates/my-theme/
├── home.php
├── theme.json
├── assets/
│   ├── app.css
│   ├── app.js
│   └── vendor/
├── images/
├── font/
├── partials/
│   ├── hero.php
│   └── footer.php
└── README.md

其中：

home.php 负责装配页面
partials/ 放主题内部拆分片段
assets/ 放构建产物
README.md 可写主题自己特有的说明，但插件总规范应以本文为准

本文章采用 CC BY-NC-SA 4.0 协议授权，转载请注明来源。
文章名称：Typecho 个人主页插件 - TypechoBio
文章链接：https://blog.lhl.one/artical/1263.html

文章目录

TypechoBio 个人主页插件

安装方式

方式一：AB-Store 一键安装（推荐）

方式二：手动安装

方式三：Git 克隆

可安装主题

TypechoBio 主题适配文档

1. 运行模型

2. 主题最小目录结构

3. home.php 的职责

4. 运行时上下文 $typechoBioContext

4.1 基础站点信息

4.2 用户信息

4.3 主题与插件信息

4.4 评论与接口信息

4.5 其他常用数据

4.6 读取示例

5. theme.json 规范

5.1 顶层字段

5.2 fields 数组支持的字段

5.3 默认值行为

6. 配置系统是怎么存的

7. 静态资源接入规范

7.1 推荐写法

7.2 资源放置建议

7.3 根路径资源的兼容

7.4 大小写问题

7.5 MIME 类型

8. 评论区接入

8.1 接入前提

8.2 最小接入方式

8.3 可用选项

8.4 共享类名

8.5 主题侧建议

9. 远程主题仓库与 zip 包要求

9.1 zip 包要求

9.2 themes.json 条目建议

10. 从现成前端项目迁移时的建议流程

第一步：先跑起来页面壳层

第二步：再接插件上下文

第三步：再接后台可配置字段

第四步：最后再接评论和 API

11. 常见坑与排查

11.1 主题不显示在后台“启用主题”里

11.2 主题显示了，但配置项不出现

11.3 默认值没有生效

11.4 资源 404

11.5 评论区不显示

11.6 主题依赖第三方 API，页面打开就报错

12. 推荐的适配清单

13. 建议的目录模板

4. 运行时上下文 `$typechoBioContext`