Typecho 主题开发超详细教程-新知幻

「从 0 到 1」的 Typecho 主题开发超详细教程，覆盖环境准备、目录结构、模板层级、变量与函数、配置面板、打包发布等全部环节。跟着做一遍即可独立开发可发布的 Typecho 主题。

阶段 1：开发环境准备

运行环境
• PHP ≥ 7.2（推荐 8.x）
• MySQL / MariaDB ≥ 5.7
• Nginx / Apache（可选宝塔、Laragon、XAMPP、LocalWP 等一键包）
安装 Typecho
• 官网下载最新版：https://typecho.org/download
• 解压到 /usr/themes/ 同级目录，按安装向导完成初始化
编辑器 & 调试
• VS Code + PHP Intelephense 插件
• 打开 config.inc.php 追加

define('__TYPECHO_DEBUG__', true);

即可在出错时看到堆栈。

阶段 2：主题最小可运行骨架（Hello World）

usr/themes/
└── HelloWorld/          ← 主题文件夹
    ├── index.php        ← 必须
    ├── screenshot.png   ← 800×600 预览图
    └── functions.php    ← 可选，配置钩子

index.php（最简版）

<?php
/**
 * Hello World
 *
 * @package HelloWorld
 * @version 1.0.0
 * @link https://example.com
 */
if (!defined('__TYPECHO_ROOT_DIR__')) exit;
$this->need('header.php');
?>
<main>
  <h1>Hello Typecho!</h1>
</main>
<?php $this->need('footer.php'); ?>

header.php

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="<?php $this->options->charset(); ?>">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title><?php $this->archiveTitle(); ?></title>
  <link rel="stylesheet" href="<?php $this->options->themeUrl('style.css'); ?>">
</head>
<body>

footer.php

<footer>&copy; <?php echo date('Y'); ?> <?php $this->options->title(); ?></footer>
</body></html>

启用主题
后台「控制台->外观」即可看到并启用。

阶段 3：模板层级与命名约定

Typecho 没有 WP 那么复杂的层级，但同样按文件名区分：

场景	模板文件
首页	index.php
独立文章	post.php
独立页面	page.php
分类/标签/搜索/日期归档	archive.php
404	404.php
评论区域	comments.php (通过 `$this->need(‘comments.php’)` 载入)

开发技巧：
• 在任意页面使用 debug($this) 可查看当前对象有哪些字段可用（需开启调试）。
• 常用判断函数：$this->is('index')、$this->is('post')、$this->is('page') 等。

阶段 4：核心输出函数与循环

4.1 文章列表循环

<?php while($this->next()): ?>
  <article>
    <h2><a href="<?php $this->permalink() ?>"><?php $this->title() ?></a></h2>
    <p><?php $this->excerpt(120, '...'); ?></p>
    <time><?php $this->date('Y-m-d'); ?></time>
  </article>
<?php endwhile; ?>

4.2 分页

<?php $this->pageNav('&laquo;', '&raquo;', 3, '...', array('wrapTag' => 'nav')); ?>

4.3 常用字段

字段	调用
站点标题	$this->options->title()
站点副标题	$this->options->description()
作者	$this->author()
分类	$this->category(‘,’, false)
标签	$this->tags(‘,’, false)
浏览数	Views_Plugin::theViews() (需装插件)

阶段 5：主题配置面板（functions.php）

新建 functions.php

<?php
function themeConfig($form) {
    $logoUrl = new Typecho_Widget_Helper_Form_Element_Text(
        'logoUrl', NULL, '', _t('站点 Logo'), _t('填写图片 URL'));
    $form->addInput($logoUrl);

    $bannerTitle = new Typecho_Widget_Helper_Form_Element_Text(
        'bannerTitle', NULL, '', _t('首页大标题'), _t('显示在首屏'));
    $form->addInput($bannerTitle);

    $sidebarSwitch = new Typecho_Widget_Helper_Form_Element_Radio(
        'sidebarSwitch', array('1' => '开启', '0' => '关闭'), '1', _t('侧边栏'));
    $form->addInput($sidebarSwitch);
}

2.使用配置

<?php if ($this->options->logoUrl): ?>
  <img src="<?php $this->options->logoUrl(); ?>" alt="logo">
<?php endif; ?>

阶段 6：样式与脚本资源管理

HelloWorld/
├── css/
│   └── main.css
├── js/
│   └── main.js
└── assets/
    └── logo.svg

在 header.php 引入

<link rel="stylesheet" href="<?php $this->options->themeUrl('css/main.css'); ?>">

在 footer.php 引入

<script src="<?php $this->options->themeUrl('js/main.js'); ?>"></script>

使用前端构建（可选）
• Sass/Webpack/Vite 把 src/ 编译到 dist/
• 在主题根新建 webpack.config.js 即可，Typecho 无额外限制。

阶段 7：评论与侧边栏

7.1 评论

新建 comments.php

<?php if ($this->allow('comment')): ?>
  <section id="comments">
    <?php $this->comments()->to($comments); ?>
    <h3><?php $comments->totalNum(); ?> 条评论</h3>
    <?php while($comments->next()): ?>
      <div class="comment" id="<?php $comments->theId(); ?>">
        <img src="<?php $comments->gravatar('40'); ?>">
        <div>
          <strong><?php $comments->author(); ?></strong>
          <time><?php $comments->date('Y-m-d H:i'); ?></time>
          <p><?php $comments->content(); ?></p>
        </div>
      </div>
    <?php endwhile; ?>
    <!-- 评论表单 -->
    <?php $this->need('comment-form.php'); ?>
  </section>
<?php endif; ?>

7.2 侧边栏

在 functions.php 注册

if (!function_exists('themeInit')) {
    function themeInit($archive) {
        Helper::addRoute('robots', '/robots.txt', 'Typecho_Widget', 'robots');
    }
}

然后 sidebar.php

<aside>
  <?php if ($this->options->sidebarSwitch): ?>
    <section>
      <h4>最新文章</h4>
      <?php $this->widget('Widget_Contents_Post_Recent', 'pageSize=5')->parse('<li><a href="{permalink}">{title}</a></li>'); ?>
    </section>
  <?php endif; ?>
</aside>

阶段 8：国际化 i18n

在主题根创建 languages/zh_CN.po/.mo
functions.php 加入

add_action('init', function() {
    load_theme_textdomain('HelloWorld', __DIR__ . '/languages');
});

模板中使用 _e('Read More', 'HelloWorld'); 或 __('Read More', 'HelloWorld');

阶段 9：打包发布即可使用当前主题

文章版权归作者所有，未经允许请勿转载。

THE END

模板资源源码资源

Typecho 主题开发超详细教程