ThinkPHP 3.1 快速入門（一）：目錄結構、入口文件、調試模式與 MVC 基礎實戰

前言

ThinkPHP 3.1 是國產 MVC 框架的經典版本，以「簡潔實用、開發體驗優先」著稱。本文為入門系列首篇，帶你從零搭建專案，掌握目錄結構、入口文件、調試模式、URL 模式、控制器/模型/視圖基礎操作，並完成第一個「讀取資料庫顯示列表」的完整流程。

一、框架目錄結構

ThinkPHP/
├─ ThinkPHP.php      框架入口文件（不可直接執行）
├─ Common/           框架公共函數
├─ Conf/             框架核心配置
├─ Extend/           框架擴展目錄
├─ Lang/             核心語言包
├─ Lib/              核心類庫
│  ├─ Behavior/      行為擴展
│  ├─ Core/          核心基類
│  ├─ Driver/        內建驅動
│  │  ├─ Cache/      快取驅動
│  │  ├─ Db/         資料庫驅動
│  │  ├─ TagLib/     標籤驅動
│  │  └─ Template/   模板引擎驅動
│  └─ Template/      內建模板引擎
└─ Tpl/              系統預設模板

注意：ThinkPHP.php 僅供專案入口文件 require，不可直接在瀏覽器訪問。

二、建立專案入口文件

1. Web 根目錄建立 app/ 子目錄（專案名）。
2. 在 app/ 下建立 index.php：

<?php
require '/path/to/ThinkPHP/ThinkPHP.php';

app/
├─ index.php          專案入口
├─ Common/            專案公共文件
├─ Conf/              專案配置
├─ Lang/              專案語言包
├─ Lib/               專案類庫
│  ├─ Action/         控制器
│  ├─ Behavior/       行為
│  ├─ Model/          模型
│  └─ Widget/         元件
├─ Runtime/           運行時目錄（快取、日誌、臨時檔）
│  ├─ Cache/
│  ├─ Data/
│  ├─ Logs/
│  └─ Temp/
└─ Tpl/               專案模板

將入口文件移至 Web 根目錄（可選）

<?php
define('APP_NAME', 'app');
define('APP_PATH', './app/');
require '/path/to/ThinkPHP/ThinkPHP.php';

此後可直接用 https://localhost/ 訪問專案。

三、開啟調試模式（強烈建議開發期啟用）

<?php
define('APP_DEBUG', true);  // 開啟調試模式
require '/path/to/ThinkPHP/ThinkPHP.php';

• 調試模式：關閉快取、詳細錯誤回報、即時生效配置修改。
• 部署模式：啟用編譯快取、隱藏錯誤、效能優先。
• 上線前只需刪除或改為 define('APP_DEBUG', false);。

四、專案配置

編輯 app/Conf/config.php，採用 PHP 陣列返回：

<?php
return array(
    'DB_TYPE'   => 'mysql',
    'DB_HOST'   => 'localhost',
    'DB_NAME'   => 'thinkphp',
    'DB_USER'   => 'root',
    'DB_PWD'    => '',
    'DB_PORT'   => 3306,
    'DB_PREFIX' => 'think_',
    // 或使用 DSN 簡化
    // 'DB_DSN' => 'mysql://root@localhost:3306/thinkphp',
);

五、控制器

• 命名規範：模組名Action.class.php（駝峰、首字母大寫）。
• 預設模組 Index，對應 Lib/Action/IndexAction.class.php。
• 預設操作 index，類別需繼承 Action，方法為 public。

class IndexAction extends Action {
    public function index() {
        echo 'hello, world!';
    }
}

六、URL 模式與請求解析

ThinkPHP 支援四種 URL 模式：

PATHINFO 分隔符可配置：'URL_PATHINFO_DEPR' => '-' 可得 /module-action-var-value/。

Apache Rewrite 規則（.htaccess）

<IfModule mod_rewrite.c>
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php/$1 [QSA,PT,L]
</IfModule>

七、視圖與模板引擎

• 內建編譯型模板引擎，語法類 Smarty（{$var}、 等）。
• 預設模板定位：Tpl/模組名/操作名.html（如 Tpl/Index/index.html）。
• 控制器輸出：$this->display(); 自動渲染對應模板。

模板範例

<html>
<head><title>hello {$name}</title></head>
<body>hello, {$name}!</body>
</html>

控制器賦值

public function index() {
    $this->name = 'thinkphp';
    $this->display();
}

八、模型與資料讀取實戰

1. 建立資料表：

CREATE TABLE `think_data` (
  `id` int(8) unsigned NOT NULL AUTO_INCREMENT,
  `data` varchar(255) NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

INSERT INTO `think_data` (`id`, `data`) VALUES
(1, 'thinkphp'), (2, 'php'), (3, 'framework');

2. 控制器使用 M() 實例化模型（無需建立模型類）：

public function index() {
    $Data = M('Data');           // 對應 think_data 表
    $this->data = $Data->select(); // 讀取所有資料
    $this->display();
}

3. 模板輸出列表：

<volist name="data" id="vo">
    {$vo.id}--{$vo.data}<br/>
</volist>

4. 瀏覽器訪問，輸出：

1--thinkphp
2--php
3--framework

九、常見問題排查

• 報錯「表不存在」：檢查 DB_PREFIX 是否正確。
• 修改配置不生效：清空 Runtime/Cache/ 目錄。
• 白屏無輸出：確認已開啟 APP_DEBUG。

結語

本篇完成了 ThinkPHP 3.1 專案從零搭建到「讀取資料庫顯示列表」的完整閉環。下一篇將深入講解資料的 CURD 操作、驗證、關聯模型等進階主題。請保持調試模式開啟，愉快編碼！