开发环境搭建

本文档帮助你搭建完整的本地开发环境。如果你只想快速体验项目，请先参考 快速开始。

环境要求

依赖	最低版本	推荐版本	验证命令
PHP	8.0+	8.2+	php -v
Composer	2.0+	最新版	composer -V
MySQL	5.7+	8.0+	mysql --version
Redis	5.0+	7.0+	redis-cli --version
Node.js	18+	20+	node -v
pnpm	8+	最新版	pnpm -v

PHP 扩展要求

确保以下 PHP 扩展已启用（php -m 查看）：

• pdo_mysql — MySQL 数据库驱动
• mbstring — 多字节字符串处理
• curl — HTTP 请求
• fileinfo — 文件类型检测（上传功能需要）
• redis — Redis 缓存驱动
• exif — 图片 EXIF 信息读取

后端环境配置

安装依赖

cd server
composer install

环境变量配置

复制 .env.example 为 .env 并编辑：

cp .env.example .env

.env 全字段说明：

字段	说明	默认值	备注
APP_DEBUG	调试模式	true	开发环境保持 true，生产必须设为 false
APP_TRACE	调试面板	false	开启后页面底部显示调试信息
APP_KEY	应用密钥	—	生产环境请生成 32+ 字符随机字符串
JWT_SECRET	JWT 签名密钥	—	用于用户认证 Token 签名
数据库 [DB]
TYPE	数据库类型	mysql	目前仅支持 MySQL
HOST	数据库地址	127.0.0.1
PORT	端口	3306
NAME	数据库名	dev007	需提前创建
USER	用户名	root
PASS	密码	root
CHARSET	字符集	utf8mb4	不建议修改
缓存 [CACHE]
DRIVER	缓存驱动	file	可选 file / redis，生产推荐 redis
EXPIRE	默认过期时间	3600	单位：秒
PREFIX	缓存键前缀	think
Session [SESSION]
TYPE	Session 驱动	file
EXPIRE	过期时间	1800	单位：秒
Redis [REDIS]
HOST	Redis 地址	127.0.0.1	Docker 环境使用容器服务名 redis
PORT	端口	6379
PASSWORD	密码	空
SELECT	数据库编号	0
队列 [QUEUE]
CONNECTOR	队列驱动	sync	可选 sync（同步）/ redis（异步），生产推荐 redis

目录权限

确保以下目录可写：

chmod -R 755 runtime
chmod -R 755 public/storage

前端环境配置（管理后台）

安装依赖

cd admin
pnpm install

TIP

如果未安装 pnpm，执行 npm install -g pnpm 安装。

环境变量

前端环境变量文件位于 admin/.env.development：

# API 代理目标地址（后端服务地址）
VITE_API_URL=http://localhost:8000

vite.config.ts 中已配置代理，开发时前端请求 /adminapi 会自动转发到后端。

IDE 推荐配置

VSCode 推荐插件：

• Vue - Official — Vue 3 语言支持
• TypeScript Vue Plugin — TS 增强
• ESLint — 代码规范检查
• UnoCSS — UnoCSS 智能提示
• Element Plus Snippets — Element Plus 代码片段

移动端环境配置（UniApp）

安装依赖

cd uniapp
pnpm install

开发方式

方式一：命令行

pnpm dev:h5           # H5 开发（浏览器）
pnpm dev:mp-weixin    # 微信小程序

方式二：HBuilderX

使用 HBuilderX 打开 uniapp/ 目录，可视化运行和调试。

微信小程序开发

1. 安装 微信开发者工具
2. 执行 pnpm dev:mp-weixin，编译产物在 dist/dev/mp-weixin/
3. 微信开发者工具导入该目录
4. 在微信开发者工具「设置 → 安全设置」中开启服务端口

数据库初始化

创建数据库

CREATE DATABASE dev007 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

方式一：安装向导（推荐）

启动后端服务后访问 http://localhost:8000/install/，安装向导会自动完成数据库初始化。

方式二：手动导入

cd server
mysql -u root -p dev007 < public/install/data/schema.sql
mysql -u root -p dev007 < public/install/data/init.sql

默认账号

角色	账号	密码
超级管理员	admin	安装时设置

启动全部服务

后端

cd server
php think run
# 默认监听 http://localhost:8000

如需启用异步队列（消息通知、操作日志等后台任务）：

php think queue:work --daemon

前端管理后台

cd admin
pnpm dev
# 默认监听 http://localhost:5173

移动端

cd uniapp
pnpm dev:h5
# 默认监听 http://localhost:5174

启动验证清单

全部服务启动后，逐项检查：

• [ ] 访问 http://localhost:5173，能看到登录页面
• [ ] 使用管理员账号登录，能看到左侧菜单
• [ ] 点击任意菜单，页面正常加载（无 404 或接口报错）
• [ ] 在列表页执行搜索，数据正常返回
• [ ] 访问 http://localhost:8000/adminapi/doc，能看到 API 文档页面