开发环境搭建

本文档将指导您搭建蝉印诊所管家的本地开发环境。

环境要求

后端开发环境

软件	最低版本	推荐版本	说明
PHP	8.4	8.4+	核心运行环境
Composer	2.5	最新版	PHP 依赖管理
MySQL	8.0	8.0+	关系型数据库
Redis	7.0	7.2+	缓存服务器
Git	2.30	最新版	版本控制

前端开发环境

软件	最低版本	推荐版本	说明
Node.js	18.0	20.x LTS	JavaScript 运行环境
npm	9.0	10.x	包管理器
pnpm	8.0	最新版	推荐的包管理器

开发工具推荐

IDE：PhpStorm、VS Code
API 测试：Postman、Apifox
数据库管理：Navicat、DataGrip、DBeaver
版本控制：SourceTree、GitKraken

PHP 环境配置

1. 安装 PHP 8.4

macOSUbuntuWindows

bash

# 使用 Homebrew 安装
brew install PHP@8.4

# 添加到 PATH
echo 'export PATH="/opt/homebrew/opt/PHP@8.4/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证安装
PHP -v

bash

# 添加 PPA 源
sudo add-apt-repository ppa:ondrej/PHP
sudo apt update

# 安装 PHP 8.4
sudo apt install PHP8.4-cli PHP8.4-fpm PHP8.4-MySQL PHP8.4-Redis \
  PHP8.4-mbstring PHP8.4-xml PHP8.4-curl PHP8.4-zip PHP8.4-gd

# 验证安装
PHP -v

bash

# 下载 PHP 8.4 Windows 版本
# https://windows.PHP.net/download/

# 解压到 C:\PHP
# 添加 C:\PHP 到系统环境变量 PATH

# 复制配置文件
copy C:\PHP\PHP.ini-development C:\PHP\PHP.ini

# 验证安装
PHP -v

2. 安装必需的 PHP 扩展

bash

# 检查已安装的扩展
PHP -m

# 必需扩展列表
# - pdo_MySQL
# - Redis
# - mbstring
# - xml
# - curl
# - zip
# - gd
# - bcmath
# - intl

3. 配置 PHP.ini

编辑 PHP.ini 文件，修改以下配置：

ini

; 基础配置
memory_limit = 256M
upload_max_filesize = 50M
post_max_size = 50M
max_execution_time = 300

; 时区设置
date.timezone = Asia/Shanghai

; 扩展启用
extension=pdo_MySQL
extension=Redis
extension=mbstring
extension=xml
extension=curl
extension=zip
extension=gd
extension=bcmath
extension=intl

; 开发环境错误显示
display_errors = On
error_reporting = E_ALL

4. 安装 Composer

bash

# 下载安装脚本
PHP -r "copy('https://getcomposer.org/installer', 'composer-setup.PHP');"

# 安装
PHP composer-setup.PHP --install-dir=/usr/local/bin --filename=composer

# 清理
PHP -r "unlink('composer-setup.PHP');"

# 验证安装
composer -V

# 配置国内镜像（可选）
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

数据库环境

1. 安装 MySQL 8.0

macOSUbuntuWindows

bash

# 使用 Homebrew 安装
brew install MySQL@8.0

# 启动服务
brew services start MySQL@8.0

# 初始化安全设置
MySQL_secure_installation

bash

# 安装 MySQL
sudo apt install MySQL-server

# 启动服务
sudo systemctl start MySQL
sudo systemctl enable MySQL

# 初始化安全设置
sudo MySQL_secure_installation

bash

# 下载 MySQL Installer
# https://dev.MySQL.com/downloads/installer/

# 运行安装程序，选择 Developer Default
# 设置 root 密码
# 配置为开机自启

2. 创建数据库

bash

# 登录 MySQL
MySQL -u root -p

# 创建数据库
CREATE DATABASE yiliaocrm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 创建用户并授权
CREATE USER 'yiliaocrm'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON yiliaocrm.* TO 'yiliaocrm'@'localhost';
FLUSH PRIVILEGES;

# 退出
EXIT;

3. 安装 Redis

macOSUbuntuWindows

bash

# 使用 Homebrew 安装
brew install Redis

# 启动服务
brew services start Redis

# 测试连接
Redis-cli ping
# 返回 PONG 表示成功

bash

# 安装 Redis
sudo apt install Redis-server

# 启动服务
sudo systemctl start Redis
sudo systemctl enable Redis

# 测试连接
Redis-cli ping

bash

# 下载 Redis Windows 版本
# https://GitHub.com/tporadowski/Redis/releases

# 解压并运行
Redis-server.exe

# 测试连接
Redis-cli.exe ping

Node.js 环境

1. 安装 Node.js

推荐使用 nvm 管理 Node.js 版本：

bash

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重载配置
source ~/.bashrc  # 或 ~/.zshrc

# 安装 Node.js 20 LTS
nvm install 20
nvm use 20

# 验证安装
node -v
npm -v

2. 安装 pnpm

bash

# 安装 pnpm
npm install -g pnpm

# 验证安装
pnpm -v

# 配置淘宝镜像（可选）
pnpm config set registry https://registry.npmmirror.com

克隆项目

1. 克隆后端项目

bash

# 从 Gitee 克隆
git clone https://gitee.com/yiliaocrm/api.git yiliaocrm-api
cd yiliaocrm-api

# 安装依赖
composer install

# 复制环境配置
cp .env.example .env

# 生成应用密钥
PHP artisan key:generate

# 配置 JWT 密钥
PHP artisan jwt:secret

2. 克隆前端项目

bash

# 从 Gitee 克隆
git clone https://gitee.com/yiliaocrm/admin.git yiliaocrm-admin
cd yiliaocrm-admin

# 安装依赖
pnpm install

# 复制环境配置
cp .env.example .env.development

配置环境变量

后端 `.env` 配置

编辑 yiliaocrm-api/.env 文件：

bash

APP_NAME="蝉印诊所管家"
APP_ENV=local
APP_KEY=base64:xxxxx
APP_DEBUG=true
APP_URL=http://localhost:8000

# 数据库配置
DB_CONNECTION=MySQL
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=yiliaocrm
DB_USERNAME=yiliaocrm
DB_PASSWORD=your_password

# Redis 配置
Redis_HOST=127.0.0.1
Redis_PASSWORD=null
Redis_PORT=6379

# JWT 配置
JWT_SECRET=xxxxx
JWT_TTL=1440

# 队列配置
QUEUE_CONNECTION=Redis

# 邮件配置（可选）
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your_email
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@example.com

# 短信配置（可选）
SMS_DRIVER=aliyun
SMS_ACCESS_KEY_ID=your_key
SMS_ACCESS_KEY_SECRET=your_secret

前端 `.env.development` 配置

编辑 yiliaocrm-admin/.env.development 文件：

bash

# 应用标题
VITE_APP_TITLE=蝉印诊所管家

# API 地址
VITE_API_BASE_URL=http://localhost:8000/api

# 上传地址
VITE_UPLOAD_URL=http://localhost:8000/api/upload

# 静态资源地址
VITE_STATIC_URL=http://localhost:8000/storage

初始化数据库

bash

cd yiliaocrm-api

# 运行数据库迁移
PHP artisan migrate

# 填充测试数据
PHP artisan db:seed

# 创建存储链接
PHP artisan storage:link

启动开发服务器

启动后端服务

bash

cd yiliaocrm-api

# 启动开发服务器
PHP artisan serve
# 服务运行在 http://localhost:8000

# 启动队列处理（新终端）
PHP artisan queue:work

# 启动任务调度（新终端，可选）
PHP artisan schedule:work

启动前端服务

bash

cd yiliaocrm-admin

# 启动开发服务器
pnpm dev
# 服务运行在 http://localhost:5173

验证安装

1. 访问后端 API

bash

# 测试健康检查
curl http://localhost:8000/api/health

# 应返回
{
  "status": "ok",
  "timestamp": "2024-01-01 12:00:00"
}

2. 访问前端应用

打开浏览器访问 http://localhost:5173

默认管理员账号：

用户名： admin
密码： admin123

3. 检查数据库连接

bash

cd yiliaocrm-api

# 测试数据库连接
PHP artisan tinker

>>> DB::connection()->getPdo();
# 无异常表示连接成功

常见问题

1. Composer 安装失败

问题： composer install 失败或超时

解决方案：

bash

# 清除缓存
composer clear-cache

# 使用国内镜像
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 重新安装
composer install --no-scripts
composer run-script post-root-package-install
composer run-script post-create-project-cmd

2. PHP 扩展缺失

问题：提示缺少某个 PHP 扩展

解决方案：

bash

# Ubuntu/Debian
sudo apt install PHP8.4-扩展名

# macOS
brew install PHP@8.4
# 然后编辑 PHP.ini 启用扩展

# Windows
# 编辑 PHP.ini，取消对应扩展的注释
extension=扩展名

3. 权限问题

问题：Laravel 提示存储目录无写入权限

解决方案：

bash

cd yiliaocrm-api

# 设置正确的权限
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

# macOS 可能需要
sudo chown -R $(whoami) storage bootstrap/cache

4. 前端 pnpm 安装失败

问题： pnpm install 失败

解决方案：

bash

# 清除缓存
pnpm store prune

# 使用淘宝镜像
pnpm config set registry https://registry.npmmirror.com

# 删除 node_modules 和锁文件重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

5. 端口占用

问题：8000 或 5173 端口被占用

解决方案：

bash

# 后端使用其他端口
PHP artisan serve --port=8001

# 前端修改 vite.config.ts
export default defineConfig({
  server: {
    port: 5174
  }
})

下一步

环境搭建完成后，您可以：

阅读 API 接口文档了解后端接口
查看代码规范了解编码标准
参考贡献指南提交代码
浏览插件开发指南开发扩展功能

开发环境搭建 ​

环境要求 ​

后端开发环境 ​

前端开发环境 ​

开发工具推荐 ​

PHP 环境配置 ​

1. 安装 PHP 8.4 ​

2. 安装必需的 PHP 扩展 ​

3. 配置 PHP.ini ​

4. 安装 Composer ​

数据库环境 ​

1. 安装 MySQL 8.0 ​

2. 创建数据库 ​

3. 安装 Redis ​

Node.js 环境 ​

1. 安装 Node.js ​

2. 安装 pnpm ​

克隆项目 ​

1. 克隆后端项目 ​

2. 克隆前端项目 ​

配置环境变量 ​

后端 .env 配置 ​

前端 .env.development 配置 ​

初始化数据库 ​

启动开发服务器 ​

启动后端服务 ​

启动前端服务 ​

验证安装 ​

1. 访问后端 API ​

2. 访问前端应用 ​

3. 检查数据库连接 ​

常见问题 ​

1. Composer 安装失败 ​

2. PHP 扩展缺失 ​

3. 权限问题 ​

4. 前端 pnpm 安装失败 ​

5. 端口占用 ​

下一步 ​

开发环境搭建

环境要求

后端开发环境

前端开发环境

开发工具推荐

PHP 环境配置

1. 安装 PHP 8.4

2. 安装必需的 PHP 扩展

3. 配置 PHP.ini

4. 安装 Composer

数据库环境

1. 安装 MySQL 8.0

2. 创建数据库

3. 安装 Redis

Node.js 环境

1. 安装 Node.js

2. 安装 pnpm

克隆项目

1. 克隆后端项目

2. 克隆前端项目

配置环境变量

后端 `.env` 配置

前端 `.env.development` 配置

初始化数据库

启动开发服务器

启动后端服务

启动前端服务

验证安装

1. 访问后端 API

2. 访问前端应用

3. 检查数据库连接

常见问题

1. Composer 安装失败

2. PHP 扩展缺失

3. 权限问题

4. 前端 pnpm 安装失败

5. 端口占用

下一步