ThinkPHP控制器开发规范-ThinkPHP-PHP中文网

thinkphp控制器文件名、类名、命名空间必须严格大小写匹配且路径一致，构造函数中不可调用redirect()或输出，仅public方法可被路由访问，命名空间须位于文件顶部无bom。

thinkphp控制器开发规范

控制器文件名和类名必须严格大小写匹配

ThinkPHP 在 Linux 服务器上完全大小写敏感，Index.php 和 index.php 是两个不同文件；class Index 和 class index 会被视为不同类。开发时若在 Windows 下忽略这点，上线后直接 404。

✅ 正确路径：app/controller/Index.php → 类名 class Index → 可通过 /index/index 访问
❌ 错误示例：app/controller/index.php 或 app/controller/IndexController.php → 路由无法解析，无报错提示，只返回 404
⚠️ 注意：namespace app\controller 必须完整、无拼写错误，少一个 controller 或多一个反斜杠，就会触发 “Class not found” 且堆栈不指向具体位置

构造函数里不能调用 `redirect()` 或输出内容

__construct() 执行时框架上下文（如 $this->request、$this->response）尚未初始化完毕，此时调用 $this->redirect() 或 echo 很可能触发 headers already sent 错误，尤其在启用输出缓冲前。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

✅ 正确做法：把权限校验、通用赋值等逻辑统一放在 initialize() 方法中——这是 ThinkPHP 预留的钩子，确保请求对象就绪
❌ 常见误写：public function __construct() { if (!auth()) { $this->redirect('login'); } } → 大概率报错或跳转失效
⚠️ 补充：_initialize()（带下划线）是 ThinkPHP 3.x 的旧写法，TP5/6 中已弃用，不要与 initialize() 混淆

只有 public 方法才能被路由访问

ThinkPHP 默认只扫描并绑定 public 修饰的方法为可访问操作（Action），private、protected 或以下划线开头的 public 方法（如 _init()）全部被跳过。

✅ 可访问：public function userList()、public function detail()
❌ 不可访问：private function checkToken()、public function _beforeWrite()、public function __invoke()
⚠️ 特别注意：方法名不能与系统保留字冲突，比如 display、error、success —— 这些已被框架内部占用，定义同名方法会导致不可预期行为

命名空间声明必须精准且位于文件最顶部

ThinkPHP 依赖 PSR-4 自动加载，namespace 必须与文件物理路径完全一致，且不能有任何前置输出（包括 BOM、空格、echo、print）。

✅ 正确写法（无空行、无 BOM、UTF-8 编码）：

<?php namespace app\controller;

use think\Controller;

class Index extends Controller
{
    public function index()
    {
        return 'ok';
    }
}

❌ 常见失败点：编辑器保存时自动加了 BOM；namespace 写成 app\controller\（末尾多斜杠）；用了中文全角空格；use 语句写在 namespace 前面
⚠️ 真实调试建议：遇到 “Class not found”，先用 php -l Index.php 检查语法，再用 hexdump -C Index.php | head 查 BOM，最后确认 composer dump-autoload 是否执行过