Filament 5.x 保姆级实战教程：从零搭建CRM系统（第 1 章）

第 1 章 环境篇：开发环境搭建与项目初始化

本章目标：在 Windows 系统上搭建完整的 PHP + Laravel + Filament 开发环境，并创建第一个可运行的 Laravel 项目。

---

1.1 本章导读

为什么要从环境搭建开始写起？

本章的设计理念是**"从零开始，一个都不能少"**——我们将从安装第一个软件开始，手把手带你走到项目运行成功的那个瞬间。

本章你将完成什么？

• 安装 PHP 8.2+ 运行环境
• 安装 Composer 包管理器
• 安装 Node.js（前端资源编译需要）
• 配置 VS Code 开发编辑器
• 创建第一个 Laravel 项目并验证运行

预估耗时

约 60-90 分钟（视网络下载速度而定）

---

1.2 技术栈概览

在动手之前，先了解一下我们将要安装的这些工具分别扮演什么角色：

工具	作用	类比理解
PHP	服务器端脚本语言	就像 JavaScript 运行在浏览器里，PHP 运行在服务器上
Composer	PHP 的包管理器	类似 Node.js 的 npm，用来下载和管理 PHP 依赖
MySQL	关系型数据库	存储应用数据的地方
Node.js + npm	JavaScript 运行环境	编译前端资源（CSS/JS）需要
Laravel	PHP Web 框架	基于 PHP 的开发框架，提供 MVC 结构和常用功能
Filament	Laravel 后台管理面板	基于 Laravel 的 UI 框架，快速生成美观的后台界面

它们之间的关系可以用下图表示：

┌─────────────────────────────────────────┐
│            Filament 后台面板            │
│         （你最终要学习和使用的）          │
├─────────────────────────────────────────┤
│              Laravel 框架               │
├─────────────────────────────────────────┤
│     PHP 语言 + Composer 包管理器         │
├─────────────────────────────────────────┤
│   MySQL 数据库 + Node.js 前端编译环境    │
└─────────────────────────────────────────┘

---

1.3 Windows 环境搭建方案选择

方案对比

方案	优点	缺点	推荐指数
Laragon（推荐）	一键安装，自动配置虚拟域名，省心智	仅 Windows 平台	⭐⭐⭐⭐⭐
XAMPP	跨平台，文档多	配置繁琐，默认端口易冲突	⭐⭐⭐
PHPStudy	国内用户多，中文文档多	广告较多，版本更新慢	⭐⭐⭐
手动安装	灵活性最高	需要自行解决各种兼容问题	⭐⭐

本书采用 Laragon 方案，它能让初学者在 10 分钟内拥有一个完整可用的开发环境，且支持自动虚拟域名（.test 后缀），非常方便。

---

1.4 安装 Laragon 集成环境

步骤 1：下载 Laragon

1. 打开浏览器，访问官网：laragon.org
2. 点击下载 Laragon Full 版本（约 180MB）
   • Full 版包含 PHP、MySQL、Apache、Nginx、Redis、Node.js 等全套工具
   • 不要下载 Lite 版，缺少必要组件

步骤 2：安装配置

1. 运行下载的 .exe 安装程序
2. 安装路径建议选择 非系统盘（如 D:\laragon），避免权限问题
3. 安装选项保持默认即可

步骤 3：首次启动与验证

1. 安装完成后，运行 Laragon
2. 在系统托盘区右键 Laragon 图标，选择 "Start All"
3. 看到以下界面表示启动成功：

┌────────────────────────────────┐
│   Laragon                      │
│   ├─ Apache: Running ✓        │
│   ├─ MySQL: Running ✓         │
│   ├─ Redis: Running ✓         │
│   └─ Node.js: Available ✓     │
└────────────────────────────────┘

步骤 4：验证各组件版本

点击 Laragon 界面的 "Terminal" 按钮，在打开的终端中依次执行：

# 验证 PHP 版本
php -v
# 预期输出：PHP 8.2.x (或更高版本)

# 验证 Composer 版本
composer -v
# 预期输出：Composer 2.x.x

# 验证 Node.js 版本
node -v
# 预期输出：v20.x.x (或更高版本)

# 验证 npm 版本
npm -v
# 预期输出：10.x.x

如果以上命令都能正常返回版本号，说明环境安装成功。

步骤 5：理解 Laragon 的"自动虚拟域名"特性

Laragon 最强大的功能之一是自动虚拟域名。当你在 www 目录下创建项目文件夹时，它会自动生成对应的 .test 本地域名。

例如：

• 项目路径：D:\laragon\www\crm-demo
• 自动域名：http://crm-demo.test

这省去了手动配置 hosts 文件和 Apache/Nginx 虚拟主机的麻烦。

---

1.5 安装 VS Code 编辑器与必要插件

安装 VS Code

1. 访问官网：code.visualstudio.com
2. 下载 Windows 版本并安装
3. 安装时勾选 "添加到 PATH" 选项，方便命令行启动

安装必要插件

打开 VS Code，点击左侧扩展图标（或按 Ctrl+Shift+X），搜索并安装以下插件：

插件名称	作用	安装量
PHP Intelephense	PHP 代码智能提示、跳转定义	1500万+
Laravel Extension Pack	Laravel Blade 语法高亮、代码片段	官方推荐
PHP Debug	PHP 断点调试支持	200万+
Auto Rename Tag	HTML/XML 标签自动重命名	必备
Prettier - Code: formatter	代码格式化	通用

安装完成后，重启 VS Code 使插件生效。

---

1.6 创建第一个 Laravel 项目

步骤 1：打开 Laragon 终端

1. 在 Laragon 主界面点击 "Terminal" 按钮
2. 确保当前目录是 D:\laragon\www（或你的 Laragon 安装目录下的 www 文件夹）

步骤 2：使用 Composer 创建项目

在终端中执行以下命令：

composer create-project laravel/laravel crm-demo

命令解析：

部分	含义
composer	调用 Composer 包管理器
create-project	创建新项目命令
laravel/laravel	Laravel 官方项目骨架包
crm-demo	你的项目名称（可自定义）

执行过程说明：

1. Composer 会从 Packagist 仓库下载 Laravel 框架及相关依赖
2. 根据网络情况，耗时约 3-10 分钟
3. 完成后会在 www 目录下生成 crm-demo 文件夹

步骤 3：验证项目创建成功

项目创建完成后，终端会显示成功信息。现在用 VS Code 打开项目：

code crm-demo

或者在 VS Code 中点击 文件 → 打开文件夹，选择 D:\laragon\www\crm-demo。

步骤 4：配置数据库连接

Laravel 使用 .env 文件管理环境配置。打开项目根目录下的 .env 文件，修改数据库配置：

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=crm_demo
DB_USERNAME=root
DB_PASSWORD=

配置说明：

配置项	值	说明
DB_CONNECTION	mysql	使用 MySQL 数据库
DB_HOST	127.0.0.1	数据库服务器地址（本地）
DB_PORT	3306	MySQL 默认端口
DB_DATABASE	crm_demo	数据库名称（待创建）
DB_USERNAME	root	Laragon 默认用户名
DB_PASSWORD	空	Laragon 默认无密码

步骤 5：创建数据库

1. 在 Laragon 界面点击 "Database" 按钮
2. 在 HeidiSQL 窗口中，右键左侧 "会话"，选择 "新建会话"
3. 填写连接信息：
   • 主机名：127.0.0.1
   • 用户名：root
   • 密码：（留空）
4. 点击连接，然后在右侧右键 "新建" → "数据库"
5. 数据库名填写 crm_demo，字符集选择 utf8mb4_unicode_ci
6. 点击确定

步骤 6：运行数据库迁移

回到 VS Code，按 Ctrl+` 打开终端（或 终端 → 新建终端），执行：

php artisan migrate

预期输出：

INFO  Preparing database.

Creating migration table .................................................. 10ms DONE

INFO  Running migrations.

2014_10_12_000000_create_users_table ...................................... 15ms DONE
2014_10_12_100000_create_password_reset_tokens_table .................... 10ms DONE
2019_08_19_000000_create_failed_jobs_table ................................ 12ms DONE
2019_12_14_000001_create_personal_access_tokens_table ..................... 15ms DONE

看到 DONE 表示迁移执行成功，Laravel 已自动创建了基础数据表。

步骤 7：启动开发服务器

在终端中执行：

php artisan serve

预期输出：

INFO  Server running on [http://127.0.0.1:8000].

Press Ctrl+C to stop the server

步骤 8：浏览器验证

1. 打开浏览器，访问 http://crm-demo.test（Laragon 自动域名）
2. 或者访问 http://127.0.0.1:8000（artisan serve 地址）
3. 你应该看到 Laravel 的欢迎页面：

恭喜！你的第一个 Laravel 项目已成功运行！

---

1.7 项目目录结构初探

创建成功后，让我们花 5 分钟了解一下 Laravel 项目的核心目录结构：

crm-demo/
├── app/                    # 应用程序核心代码
│   ├── Http/               # HTTP 请求处理
│   │   └── Controllers/    # 控制器
│   ├── Models/             # 数据模型（Eloquent）
│   └── Providers/          # 服务提供者
├── bootstrap/              # 框架启动文件
├── config/                 # 配置文件
├── database/               # 数据库相关
│   ├── factories/          # 模型工厂（测试数据）
│   ├── migrations/         # 数据库迁移文件
│   └── seeders/            # 数据填充器
├── public/                 # 网站根目录
│   └── index.php           # 入口文件
├── resources/              # 资源文件
│   ├── css/                # CSS 文件
│   ├── js/                 # JavaScript 文件
│   └── views/              # Blade 视图模板
├── routes/                 # 路由定义
│   ├── web.php             # Web 路由
│   ├── api.php             # API 路由
│   └── console.php         # 控制台路由
├── storage/                # 运行时存储（日志、缓存等）
├── tests/                  # 测试代码
├── .env                    # 环境变量
├── composer.json           # PHP 依赖定义
└── artisan                 # Laravel 命令行工具

重点目录记忆口诀：

• app/Models：数据模型（对应数据库表）
• app/Http/Controllers：控制器（处理请求逻辑）
• database/migrations：迁移文件（定义表结构）
• routes/web.php：路由（URL 映射到控制器）
• resources/views：视图（HTML 模板）

---

1.8 本章实战验收

完成以下检查清单，确认环境搭建成功：

检查项	命令/操作	预期结果
PHP 版本	php -v	PHP 8.2.x 或更高
Composer 版本	composer -v	Composer 2.x.x
Node.js 版本	node -v	v18.x.x 或更高
Laragon 服务	Laragon 界面	Apache 和 MySQL 显示 Running
数据库连接	HeidiSQL 连接	能连接并创建数据库
项目创建	composer create-project	无报错完成
数据库迁移	php artisan migrate	显示所有迁移 DONE
服务启动	php artisan serve	显示 http://127.0.0.1:8000
浏览器访问	访问 http://crm-demo.test	显示 Laravel 欢迎页

---

1.9 本章小结

在本章中，我们完成了开发环境的完整搭建：

1. 安装了 Laragon —— Windows 上最省心的 PHP 集成环境
2. 配置了 VS Code —— 安装了 PHP/Laravel 开发必备插件
3. 创建了第一个 Laravel 项目 —— 使用 Composer 一键创建
4. 配置并连接了数据库 —— 创建了 MySQL 数据库并运行迁移
5. 成功启动了项目 —— 在浏览器中看到了 Laravel 欢迎页

关键概念回顾：

• Composer：PHP 的包管理器，类似 npm
• Artisan：Laravel 的命令行工具，php artisan 打头的都是它
• Migration（迁移）：用代码定义数据库结构，可版本控制
• .env：环境配置文件，存放敏感信息（数据库密码等）

下一步预告：

第 2 章将带你快速掌握 Laravel 的核心概念（MVC、Eloquent 模型、路由等），为第 3 章学习 Filament 打下坚实基础。不用担心，我们只学 Filament 用得上的部分，不会陷入 Laravel 的每一个细节。

---

1.10 课后练习

练习题 1：环境验证

在终端中依次执行以下命令，截图保存结果：

php -v
composer -v
node -v
npm -v

练习题 2：探索 Artisan

执行以下命令，观察输出并记录每个命令的作用：

php artisan list              # 查看所有可用命令
php artisan --version         # 查看 Laravel 版本
php artisan route:list        # 查看所有路由
php artisan db:show           # 查看数据库状态

练习题 3：创建测试数据表

尝试执行以下命令，观察会发生什么：

php artisan make:migration create_test_table

然后打开 database/migrations/ 目录，找到新生成的文件，观察文件命名和内容结构。

---

本章配套资源

• 本章代码：无（环境搭建，无代码变更）
• 下一章预告：第 2 章 基础篇 —— Laravel 核心概念快速入门
• 常见问题：如遇到端口冲突、权限问题，参考附录 A

---

第 1 章完