后端二次开发指南（小白版）
📖 本指南专门针对后端（ThinkPHP 6）的二次开发，从零开始教你如何配置、开发和部署后端服务。
📋 目录
- 技术栈介绍
后端使用的技术栈：
技术
版本
说明
| PHP | 8.0+ | 服务端开发语言 |
| ThinkPHP | 6.0+ | PHP 开发框架 |
| MySQL | 5.7+ | 主数据库 |
| Redis | 7.4+ | 缓存和队列 |
| PostgreSQL | 17.5 | 向量数据库（可选） |
| Composer | 最新版 | PHP 包管理工具 |
核心依赖包：
- ✅ topthink/framework - ThinkPHP 框架核心
- ✅ topthink/think-orm - ORM 数据库操作
- ✅ topthink/think-queue - 队列服务
- ✅ w7corp/easywechat - 微信开发 SDK
- ✅ phpoffice/phpspreadsheet - Excel 处理
- ✅ firebase/php-jwt - JWT 认证
- ✅ qiniu/php-sdk - 七牛云 SDK
- ✅ aliyuncs/oss-sdk-php - 阿里云 OSS SDK
项目特点：
- ✅ 多应用模式（adminapi、api、common）
- ✅ RESTful API 设计
- ✅ JWT Token 认证
- ✅ 队列任务处理
- ✅ 缓存优化
- ✅ 文件上传管理
- ✅ 权限控制系统
- 开始之前的准备
2.1 安装 PHP 8.0+
Windows 安装方式：
方式一：使用集成环境（推荐新手）
- 下载 phpstudy 或 XAMPP
- 安装后选择 PHP 8.0 或更高版本
- 启动 Apache 和 MySQL 服务
方式二：独立安装
- 下载地址：https://windows.php.net/download/
- 下载 PHP 8.0+ 版本（Thread Safe）
- 解压到指定目录（如
C:\php）
- 配置环境变量
验证安装：
php -v
2.2 必须启用的 PHP 扩展
编辑 php.ini 文件，取消以下扩展的注释（去掉前面的分号 ;）：
extension=curl
extension=fileinfo
extension=gd
extension=mbstring
extension=openssl
extension=pdo_mysql
extension=redis
extension=zip
extension=iconv
修改后重启 PHP 服务。
2.3 安装 Composer
下载安装：
验证安装：
composer -v
配置国内镜像（加速下载）：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
2.4 安装 MySQL
使用 phpstudy/XAMPP：
独立安装：
推荐数据库管理工具：
2.5 安装 Redis
Windows 安装：
- 下载：https://github.com/microsoftarchive/redis/releases
- 解压后运行
redis-server.exe
或使用 Docker：
docker run -d -p 6379:6379 --name redis redis:7.4
验证 Redis 是否运行：
redis-cli ping
返回 PONG 说明正常
- 首次安装配置
步骤 1：进入后端目录
在项目根目录下
cd server
步骤 2：安装依赖包
使用 Composer 安装依赖（首次较慢，请耐心等待 5-15 分钟）
composer install
⚠️ 重要提示：
- 安装前确认 PHP 版本是 8.0+
- 如果安装失败，请查看本文档「常见问题」部分
- 确保已配置 Composer 国内镜像
安装成功的标志：
- 终端没有报错
- 生成了
vendor 文件夹
- 生成了
composer.lock 文件
步骤 3：复制环境配置文件
在 server 目录下执行（Windows 系统）
copy .example.env .env
Mac/Linux 系统：
cp .example.env .env
- 环境配置详解
打开 server/.env 文件，配置以下内容：
4.1 基础配置
是否开启调试模式（开发环境设为 true，生产环境设为 false）
APP_DEBUG = true
[APP]
时区设置
DEFAULT_TIMEZONE = Asia/Shanghai
4.2 数据库配置（MySQL）
[DATABASE]
数据库类型
TYPE = mysql
数据库地址（本地开发用 127.0.0.1）
HOSTNAME = 127.0.0.1
数据库名（需要先创建）
DATABASE = chatmoney
数据库用户名
USERNAME = root
数据库密码
PASSWORD = root
数据库端口
HOSTPORT = 3306
字符集
CHARSET = utf8mb4
是否开启调试
DEBUG = true
表前缀
PREFIX = cw_
配置说明：
DATABASE：数据库名称，需要先在 MySQL 中创建USERNAME：MySQL 用户名，默认是 rootPASSWORD：MySQL 密码，根据你的实际密码填写PREFIX：数据表前缀，默认是 cw_
4.3 PostgreSQL 配置（可选，用于向量搜索）
[PGSQL]
HOSTNAME = 127.0.0.1
DATABASE = postgres
USERNAME = postgres
PASSWORD = 123456
HOSTPORT = 5432
CHARSET = utf8mb4
PREFIX = cw_
4.4 Redis 配置（缓存和队列）
[CACHE]
缓存驱动（使用 Redis）
DRIVER = redis
Redis 地址
HOST = 127.0.0.1
Redis 端口
PORT = 6379
Redis 密码（没有密码留空）
PASSWORD = ""
[QUEUE]
队列名称
NAME = chatmoney
队列使用 Redis
HOST = 127.0.0.1
PORT = 6379
PASSWORD = ""
4.5 项目配置
[PROJECT]
是否演示环境（开发环境设为 false）
DEMO_ENV = false
系统唯一标识（自定义，建议使用项目名称）
UNIQUE_IDENTIFICATION = chatmoney
4.6 语言配置
[LANG]
默认语言
DEFAULT_LANG = zh-cn
- 启动开发服务器
5.1 创建数据库
在安装服务之前，先创建数据库：
CREATE DATABASE IF NOT EXISTS chatmoney
DEFAULT CHARACTER SET utf8mb4
DEFAULT COLLATE utf8mb4_unicode_ci;
5.2 安装数据库（首次运行）
方式一：通过安装程序
- 启动 PHP 服务器：
在 server/public 目录下
cd public
php -S 127.0.0.1:8000
-
访问安装页面：
http://127.0.0.1:8000/install
-
按照提示完成安装流程
方式二：手动导入 SQL
如果项目提供了 SQL 文件，使用数据库管理工具导入。
5.3 启动开发服务器
方式一：使用 PHP 内置服务器（推荐开发环境）
在 server/public 目录下
cd public
php -S 127.0.0.1:8000
方式二：使用 phpstudy/XAMPP
- 配置虚拟主机，指向
server/public 目录
- 重启服务
方式三：使用 Nginx
参考 docker/config/nginx/conf.d/ 中的配置文件。
5.4 测试后端服务
访问：http://127.0.0.1:8000/api/index/config
如果返回 JSON 数据，说明后端配置成功！
{
"code": 1,
"msg": "成功",
"data": {
// ... 配置数据
}
}
5.5 启动队列服务（可选）
如果项目使用了队列功能，需要启动队列监听：
在 server 目录下
php think queue:listen
💡 提示：队列服务需要一直运行，建议使用 supervisor 等进程管理工具。
- 目录结构说明
server/
├── app/ # 应用目录
│ ├── adminapi/ # 管理后台 API
│ │ ├── controller/ # 控制器（处理请求）
│ │ ├── logic/ # 业务逻辑（复杂业务）
│ │ ├── lists/ # 列表类（数据列表）
│ │ ├── validate/ # 验证器（参数验证）
│ │ └── service/ # 服务类
│ │
│ ├── api/ # 前台 API
│ │ ├── controller/
│ │ ├── logic/
│ │ ├── lists/
│ │ └── validate/
│ │
│ ├── common/ # 公共模块
│ │ ├── cache/ # 缓存类
│ │ ├── command/ # 命令行
│ │ ├── enum/ # 枚举类
│ │ ├── logic/ # 公共逻辑
│ │ ├── model/ # 数据模型
│ │ ├── service/ # 公共服务
│ │ └── ...
│ │
│ ├── queue/ # 队列任务
│ ├── common.php # 公共函数
│ ├── event.php # 事件定义
│ ├── middleware.php # 中间件
│ └── service.php # 服务定义
│
├── config/ # 配置文件
│ ├── app.php # 应用配置
│ ├── database.php # 数据库配置
│ ├── cache.php # 缓存配置
│ ├── queue.php # 队列配置
│ ├── ai.php # AI 模型配置
│ └── ...
│
├── public/ # 公共访问目录（Web 根目录）
│ ├── admin/ # 管理后台前端文件
│ ├── mobile/ # 移动端前端文件
│ ├── pc/ # PC 端前端文件
│ ├── index.php # 入口文件
│ └── ...
│
├── route/ # 路由配置
│ └── app.php # 应用路由
│
├── runtime/ # 运行时文件（缓存、日志等）
├── vendor/ # Composer 依赖
├── .env # 环境配置文件
├── composer.json # Composer 配置
└── think # 命令行工具
- 开发技巧
7.1 创建一个新的 API 接口
以创建「获取文章列表」接口为例。
第 1 步：创建控制器
在 server/app/api/controller/ 下创建控制器：
dataLists(new ArticleLists());
}
/**
* 获取文章详情
* @return \think\response\Json
*/
public function detail()
{
$id = $this->request->get('id/d');
$article = \app\common\model\Article::find($id);
if (empty($article)) {
return $this->fail('文章不存在');
}
return $this->success('获取成功', $article);
}
/**
* 创建文章
* @return \think\response\Json
*/
public function add()
{
$params = (new \app\api\validate\ArticleValidate())->post()->goCheck();
\app\common\model\Article::create($params);
return $this->success('创建成功');
}
}
第 2 步：创建列表类
在 `server/app/api/lists/` 下创建列表类：
'desc'];
}
/**
* 列表数据
*/
public function lists(): array
{
return Article::where($this->where())
->field($this->fields())
->order($this->order())
->limit($this->limitOffset, $this->limitLength)
->select()
->toArray();
}
/**
* 总数
*/
public function count(): int
{
return Article::where($this->where())->count();
}
}
第 3 步：创建数据模型
在 `server/app/common/model/` 下创建模型：
where('title', 'like', '%' . $value . '%');
}
}
第 4 步：创建验证器（可选）
在 `server/app/api/validate/` 下创建验证器：
'require|length:1,200',
'content' => 'require',
'image' => 'require',
];
protected $message = [
'title.require' => '标题不能为空',
'title.length' => '标题长度不能超过200个字符',
'content.require' => '内容不能为空',
'image.require' => '封面图不能为空',
];
}
第 5 步：配置路由（可选）
ThinkPHP 6 支持自动路由，默认可以通过以下地址访问：
GET http://127.0.0.1:8000/api/article/lists # 文章列表
GET http://127.0.0.1:8000/api/article/detail # 文章详情
POST http://127.0.0.1:8000/api/article/add # 创建文章
---
7.2 数据库查询示例
基础查询
use app\common\model\Article;
// 查询所有
$list = Article::select();
// 查询单条
$article = Article::find(1);
// 条件查询
$list = Article::where('status', 1)
->where('create_time', '>', time() - 86400)
->select();
// 分页查询
$list = Article::where('status', 1)
->page(1, 10)
->select();
// 统计
$count = Article::where('status', 1)->count();
// 聚合
$total = Article::sum('view_count');
关联查询
// 一对一
class Article extends BaseModel
{
public function user()
{
return $this->hasOne(User::class, 'id', 'user_id');
}
}
// 使用
$article = Article::with('user')->find(1);
echo $article->user->name;
// 一对多
class User extends BaseModel
{
public function articles()
{
return $this->hasMany(Article::class, 'user_id', 'id');
}
}
// 使用
$user = User::with('articles')->find(1);
foreach ($user->articles as $article) {
echo $article->title;
}
高级查询
// 原生 SQL
$list = Db::query('SELECT * FROM cw_article WHERE status = ?', [1]);
// 链式查询
$list = Article::where('status', 1)
->whereBetween('create_time', [strtotime('-7 day'), time()])
->whereIn('category_id', [1, 2, 3])
->order('id', 'desc')
->limit(10)
->select();
// 子查询
$subQuery = Article::where('status', 1)->field('user_id')->buildSql();
$list = User::whereRaw("id IN {$subQuery}")->select();
---
7.3 使用缓存
use think\facade\Cache;
// 设置缓存（永久）
Cache::set('key', 'value');
// 设置缓存（带过期时间，单位：秒）
Cache::set('key', 'value', 3600);
// 获取缓存
$value = Cache::get('key');
// 获取缓存，不存在则设置默认值
$value = Cache::get('key', 'default');
// 删除缓存
Cache::delete('key');
// 清空缓存
Cache::clear();
// 自增
Cache::inc('counter');
// 自减
Cache::dec('counter');
// 判断是否存在
if (Cache::has('key')) {
// ...
}
// 记住：如果不存在则设置并返回
$value = Cache::remember('key', function() {
// 这里是获取数据的逻辑
return '数据';
}, 3600);
---
7.4 使用队列
创建队列任务
在 `server/app/queue/` 下创建队列任务：
delete();
}
/**
* 任务失败处理
* @param $data
*/
public function failed($data)
{
// 任务失败后的处理
\think\facade\Log::error('邮件发送失败：' . json_encode($data));
}
}
推送任务到队列
use think\facade\Queue;
// 推送任务
Queue::push('app\queue\SendEmailJob', [
'email' => 'user@example.com',
'content' => '邮件内容'
]);
// 延迟推送（延迟 60 秒执行）
Queue::later(60, 'app\queue\SendEmailJob', [
'email' => 'user@example.com',
'content' => '邮件内容'
]);
启动队列监听
在 server 目录下
php think queue:listen
---
7.5 文件上传处理
request->file('file');
// 验证文件
$validate = [
'size' => 2 * 1024 * 1024, // 2MB
'ext' => 'jpg,jpeg,png,gif'
];
if (!$file->check($validate)) {
return $this->fail($file->getError());
}
// 上传文件
$result = UploadService::image($file);
return $this->success('上传成功', $result);
} catch (\Exception $e) {
return $this->fail($e->getMessage());
}
}
}
---
8. 数据库操作
8.1 创建数据表
方式一：使用数据库管理工具
使用 Navicat 或 phpMyAdmin 创建表。
方式二：使用迁移文件
table('article', [
'engine' => 'InnoDB',
'collation' => 'utf8mb4_unicode_ci',
'comment' => '文章表'
]);
$table->addColumn('title', 'string', ['limit' => 200, 'comment' => '标题'])
->addColumn('content', 'text', ['comment' => '内容'])
->addColumn('author', 'string', ['limit' => 50, 'comment' => '作者'])
->addColumn('status', 'integer', ['default' => 0, 'comment' => '状态：0=草稿 1=发布'])
->addColumn('create_time', 'integer', ['default' => 0])
->addColumn('update_time', 'integer', ['default' => 0])
->addColumn('delete_time', 'integer', ['default' => 0])
->addIndex(['status'])
->create();
}
}
8.2 数据库备份
使用命令行备份
mysqldump -u root -p chatmoney > backup.sql
恢复数据库
mysql -u root -p chatmoney < backup.sql
---
9. 常用命令
9.1 ThinkPHP 命令
清除缓存
php think clear
查看所有命令
php think
创建控制器
php think make:controller api/Article
创建模型
php think make:model common/Article
创建验证器
php think make:validate Article
队列监听
php think queue:listen
查看路由
php think route:list
优化类库映射文件
php think optimize:autoload
生成数据表字段缓存
php think optimize:schema
9.2 Composer 命令
安装依赖
composer install
更新依赖
composer update
添加新包
composer require package/name
删除包
composer remove package/name
清除缓存
composer clear-cache
优化自动加载
composer dump-autoload
---
10. 常见问题解决
问题 1：Composer 安装失败
解决方法：
配置国内镜像
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
清除缓存重试
composer clear-cache
composer install
如果还是失败，尝试忽略平台要求
composer install --ignore-platform-reqs
---
问题 2：数据库连接失败
错误提示：
Connection failed: Access denied for user 'root'@'localhost'
解决方法：
1. 检查 `.env` 中数据库配置是否正确
2. 确认 MySQL 服务是否启动
3. 测试数据库连接：
mysql -u root -p
4. 确认数据库用户权限
---
问题 3：Redis 连接失败
错误提示：
Connection refused [tcp://127.0.0.1:6379]
解决方法：
1. 启动 Redis 服务
2. Windows: 运行 `redis-server.exe`
3. 检查端口是否被占用
4. 修改 `.env` 中 Redis 配置
---
问题 4：PHP 扩展缺失
错误提示：
ext-redis is missing from your system
解决方法：
1. 编辑 `php.ini`
2. 取消注释对应扩展：
extension=redis
3. 重启 PHP 服务
---
问题 5：访问 404
解决方法：
1. 确认访问的是 `public` 目录
2. 检查 `.htaccess` 或 Nginx 配置
3. 使用 PHP 内置服务器测试：
cd public
php -S 127.0.0.1:8000
---
问题 6：权限不足
Linux 系统：
设置目录权限
chmod -R 777 runtime
chmod -R 777 public/uploads
---
11. 快速参考
11.1 常用命令汇总
安装依赖
composer install
启动开发服务器
cd public && php -S 127.0.0.1:8000
清除缓存
php think clear
队列监听
php think queue:listen
创建控制器
php think make:controller api/Article
创建模型
php think make:model common/Article
---
11.2 配置文件位置
文件
路径
说明
| 环境配置 | `server/.env` | 数据库、缓存等配置 |
| 应用配置 | `server/config/app.php` | 应用基础配置 |
| 数据库配置 | `server/config/database.php` | 数据库配置 |
| 缓存配置 | `server/config/cache.php` | 缓存配置 |
| 队列配置 | `server/config/queue.php` | 队列配置 |
| 路由配置 | `server/route/app.php` | 路由配置 |
---
11.3 开发流程速查
首次部署：
1. cd server
2. composer install
3. copy .example.env .env
4. 编辑 .env，配置数据库等信息
5. 创建数据库
6. 访问安装程序或导入 SQL
7. cd public && php -S 127.0.0.1:8000
8. 测试接口：http://127.0.0.1:8000/api/index/config
日常开发：
1. cd server/public
2. php -S 127.0.0.1:8000
3. 编写代码
4. 测试接口
---
11.4 API 响应格式
成功响应：
{
"code": 1,
"msg": "成功",
"data": {
// 数据内容
}
}
失败响应：
{
"code": 0,
"msg": "错误信息",
"data": null
}
列表响应：
{
"code": 1,
"msg": "成功",
"data": {
"lists": [...],
"count": 100,
"page_no": 1,
"page_size": 10
}
}
---
🎯 总结
本指南涵盖了后端二次开发的所有关键步骤：
1. ✅ 环境准备（PHP、Composer、MySQL、Redis）
2. ✅ 安装配置（依赖、环境文件、数据库）
3. ✅ 开发调试（启动服务、接口开发）
4. ✅ 数据库操作（查询、模型、缓存）
5. ✅ 高级功能（队列、文件上传）
6. ✅ 问题解决（常见错误处理）
推荐学习资源：
- ThinkPHP 6 官方文档：https://www.kancloud.cn/manual/thinkphp6_0/
- PHP 官方文档：https://www.php.net/
- MySQL 教程：https://www.runoob.com/mysql/
祝你开发顺利！🚀
联系客服