PTCMS 是运行在 PTAdmin 上的内容管理插件，负责栏目、内容归档、内容模型、模板指令和前台内容读取等功能。本文重点介绍 CMS 插件目录、网站主题和日常建站时的文件定位方法。

与基础篇衔接：如果你还不熟悉项目根目录、网站运行目录或上传文件位置，请先阅读 PTAdmin 目录结构介绍。本文在这套基础结构上继续说明 PTCMS 的组成，不再重复展开通用配置、日志和依赖目录。

以下路径均相对于 PTAdmin 项目根目录。插件结构以 PTCMS 1.0.8 为参考，主题部分以当前站点的 default 主题举例；实际文件请以使用的插件和主题版本为准。Linux 下目录名区分大小写，addons/Cms/ 中的 Cms 不能写成 cms。

一、PTCMS 在项目中的三个主要位置

CMS 功能代码位于 addons/Cms/，处理栏目、内容、路由和模板指令等功能。

前台页面模板位于 templates/主题名/，决定页面结构和内容如何展示。

主题静态资源位于 public/templates/主题名/，供浏览器加载样式、脚本和主题配图。

PTAdmin 项目根目录/
├── addons/
│   └── Cms/                  CMS 插件功能
├── templates/
│   └── default/              前台模板示例
└── public/
    └── templates/
        └── default/          配套静态资源示例

PTCMS 使用同一个 PTAdmin 项目的运行环境和网站入口。安装 CMS 后，无需把网站运行目录改成 addons/Cms/ 或 templates/。

二、CMS 插件内部结构

需要了解功能实现或进行插件开发时，重点查看 addons/Cms/。以下为主要目录与文件：

addons/Cms/
├── manifest.json        插件信息与资源声明
├── Bootstrap.php        插件启动逻辑
├── Installer.php        插件安装逻辑
├── Config/              插件配置
├── Http/
│   ├── Controllers/     请求控制器
│   └── Requests/        请求校验
├── Models/              CMS 数据模型
├── Service/             CMS 业务服务
├── Providers/           服务注册
├── Routes/
│   ├── admin.php        后台路由
│   ├── api.php          API 路由
│   └── web.php          Web 路由
├── Response/
│   ├── Views/           插件自带视图
│   ├── Lang/            插件语言资源
│   └── Models/          响应相关模型定义
├── Expose/
│   └── Directives/      模板指令相关实现
├── Database/
│   ├── Migrations/      插件数据库迁移
│   └── Seeders/         插件初始化数据
├── Assets/              插件静态资源
├── Commands/            插件命令
└── docs/                随插件提供的开发资料

1. 请求、业务与数据访问

Routes/ 声明插件路由，Http/Controllers/ 处理请求，Http/Requests/ 负责请求校验。定位一个功能时，可以从路由找到控制器，再继续查看相关业务逻辑。

Service/ 组织业务处理，Models/ 组织 CMS 数据访问。Database/ 中保存的是数据库迁移与初始化逻辑，文章正文等业务数据由数据库管理。

2. 插件声明、配置与注册

manifest.json 描述插件信息和资源位置；Config/ 保存插件配置；Providers/、Bootstrap.php 与 Installer.php 分别承担服务注册、启动或安装相关职责。

日常内容维护通常不需要修改这些文件。直接修改官方插件源码前，应做好备份并评估升级覆盖的影响。

3. 模板指令与插件资源

Expose/Directives/ 包含模板指令相关实现。编写主题时，可结合 模板指令工具 了解调用方式；使用现有指令读取栏目或内容，通常无需改动其底层实现。

Response/Views/ 是插件自带视图，Assets/ 是插件静态资源。它们与网站主题的模板、配图和样式各有用途，修改页面前应确认实际加载来源。

三、前台模板放在哪里

1. 当前主题的模板目录

以 default 为例，模板位于 templates/default/，通常是以 .blade.php 结尾的 Blade 文件。

主题可以按首页、栏目列表、内容详情和公共部分组织文件。当前站点的例子包括：

  • index.blade.php：首页模板。
  • layouts/：公共布局。
  • partials/：可复用的局部模板。
  • docs/：当前主题的文档页面模板。

这些是当前主题的组织示例，不是所有 PTCMS 主题必须采用的固定目录。更换主题后，应以新主题实际提供的文件为准。

2. 如何找到某个栏目的页面文件

  1. 确认网站当前使用的主题。
  2. 查看该栏目的列表模板或详情模板设置。
  3. 在当前主题中定位对应文件，核对它引用的公共布局和局部模板。
  4. 确认修改范围后再调整，并检查该模板是否被其他栏目共用。

主题模板与插件视图：templates/主题名/ 是网站主题；addons/Cms/Response/Views/ 是插件自带视图。当前插件支持视图回退，最终加载位置取决于主题和视图配置，不能只凭一个相似的文件名判断。

四、静态资源与上传图片怎么区分

1. 主题配套资源

默认主题的配套资源位于 public/templates/default/，可包含 css/、js/ 和 static/ 等目录。页面装饰图、主题样式和交互脚本通常从这里加载。

例如，磁盘文件 public/templates/default/css/app.css 对应公开地址 /templates/default/css/app.css。网站入口已经指向 public/，所以访问地址不再添加一层 /public。

2. 文章上传图片

后台上传的封面、正文图片和附件属于内容数据，不应直接当作主题配图处理。它们的位置取决于存储驱动，可能在本地公开存储中，也可能在对象存储服务上。

本地文件与 public/storage 的对应关系，见 PTAdmin 目录结构介绍中的上传文件说明。迁移主题与迁移上传文件是不同的工作，备份网站时需要分别确认。

五、改正文、改模板还是改插件

只调整某篇文章：在后台编辑这篇文章的富文本正文，例如标题层级、段落、代码块和内链。文章内容由 CMS 管理，不需要直接修改公共模板。

调整一类页面的展示：查找该栏目使用的主题模板及配套资源。公共布局或共享模板的修改，可能同时影响多个页面。

扩展 CMS 功能：先核对现有插件能力，再定位插件路由、控制器和服务等实现。项目级扩展与官方插件源码应明确区分，便于后续维护和升级。

六、建站时的定位顺序

  • 找首页、栏目或文章页面：先确认当前主题和栏目模板，再查 templates/主题名/。
  • 找页面样式、脚本和主题配图：查 public/templates/主题名/。
  • 找 CMS 的业务实现：查 addons/Cms/Http/、Service/ 和 Models/。
  • 找模板指令实现：查 addons/Cms/Expose/Directives/。
  • 找文章正文与栏目数据：进入 CMS 后台管理对应记录。
  • 遇到运行目录、权限或日志问题：回到 PTAdmin 基础目录与环境配置排查。

继续阅读：PTCMS 简介 · PTCMS 安装