# RaiseEngine Lite

**Repository Path**: 494901823/raise-engine-lite

## Basic Information

- **Project Name**: RaiseEngine Lite
- **Description**: RaiseEngine Lite
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RaiseEngine Lite - 开发环境搭建指南

> **项目地址：** `D:\WorkBuddyDev\laravel-filament`
>
> **最后更新：** 2026-06-12
>
> **⚠️ 注意：** 本文档记录了搭建过程中遇到的所有坑和解决方案，如果重建环境请务必参考。

---

## 一、技术栈确认

| 组件 | 推荐版本 | 说明 |
|------|---------|------|
| PHP | **8.3.29** | 用 Laragon 切换，不可低于 8.3 |
| Laravel | **11.x** | 指定 `^11.0`，不要用 13（Filament 不兼容） |
| Filament | **3.2.x** | 目前最高支持 Laravel 12 |
| 数据库 | **SQLite** | 开发环境默认使用 |
| Composer | 最新版 | 已升级到 2.10.1 |

---

## 二、完整安装步骤

### 第 1 步：切换 PHP 版本

Laragon 菜单 → **PHP → Switch PHP Version → 8.3.29**

验证：
```bash
php -v
# → PHP 8.3.29
```

> ⚠️ **注意：** 如果版本号还是 8.1，说明你打开的终端（CMD/Git Bash）是旧的，关掉重新打开。

### 第 2 步：创建 Laravel 11 项目

```bash
cd D:\WorkBuddyDev\laravel-filament
rm -rf demo-app
composer create-project laravel/laravel:^11.0 demo-app --prefer-dist --no-install
```

> **为什么要 `--no-install`？**
>
> 因为 Composer 的 `create-project` 会自动执行 `post-create-project-cmd` 脚本（生成 APP_KEY 等），但这些脚本需要 vendor 目录已存在。如果直接装会被安全公告阻塞，加 `--no-install` 跳过自动安装，后面手动控制。

### 第 3 步：忽略安全公告并装依赖

```bash
cd D:\WorkBuddyDev\laravel-filament\demo-app
composer config policy.advisories.block false
composer install
```

> **为什么要加 `policy.advisories.block false`？**
>
> Composer 从 2.4+ 开始默认阻止安装有已知安全漏洞的包版本。Laravel 11.x 的早期版本有一些安全公告，但仅影响线上生产环境。开发阶段可以忽略，项目上线前再 `composer update` 到修复版本。

### 第 4 步：生成 APP_KEY

```bash
php artisan key:generate
```

### 第 5 步：配置 SQLite

项目创建后 `.env` 默认已配好 SQLite：
```
DB_CONNECTION=sqlite
```

无需手动修改。如果要用 MySQL 再自己改。

### 第 6 步：安装 Filament

```bash
composer config policy.advisories.block false
composer require filament/filament:"^3.2" -W
```

> **注意：** 只能用 `^3.2`，最新的 Filament 4.x 尚未发布。
>
> 如果报 `ext-zip` 缺失，加参数：`--ignore-platform-req=ext-zip`

### 第 7 步：配置 Filament Panel

```bash
php artisan filament:install --panels
```

安装过程会问你：
- **Panel ID** → 直接回车（默认 `admin`）
- 新版不会问 Panel path，自动生成在 `app/Providers/Filament/AdminPanelProvider.php`，路径默认为 `/admin`

验证文件：
```bash
cat app/Providers/Filament/AdminPanelProvider.php
# 确认有 ->path('admin')
```

### 第 8 步：创建管理员用户

```bash
php artisan make:filament-user
```

按提示输入 Name / Email / Password。

### 第 9 步：启动开发服务器

```bash
php artisan serve
```

浏览器打开：**http://127.0.0.1:8000/admin**

---

## 三、开发环境优化

### 默认服务器太慢？

`php artisan serve` 是 PHP 内置服务器，单进程、无 OPCache，开发时慢是正常的。

**方案一：启用 OPCache**

编辑 `D:\Laragon\bin\php\php-8.3.29-Win32-vs16-x64\php.ini`，去掉注释：

```ini
zend_extension=opcache
opcache.enable=1
opcache.enable_cli=1
```

**方案二：缓存优化**

```bash
php artisan optimize
php artisan view:cache
php artisan config:cache
```

**方案三：用 Laragon Nginx**

直接点 Laragon 界面上的 **启动所有** 按钮，用 Nginx + Apache 跑比 `php artisan serve` 快很多。

---

## 四、常见问题和解决方案

### Q1：PHP 版本问题

```
Cannot use laravel/laravel's latest version v13.8.0 as it requires php ^8.3
```

**原因：** PHP 版本太低。
**解决：** Laragon → PHP → Switch PHP Version → **8.3.29**

### Q2：安全公告阻塞安装

```
these were not loaded, because they are affected by security advisories ("PKSA-xxx")
```

**原因：** Composer 阻止安装有安全公告的包。
**解决：**
```bash
composer config policy.advisories.block false
composer install
```

### Q3：Filament 版本不兼容

```
filament/filament[v3.2.xxx] require illuminate/console ^10.0
```

**原因：** 你装的是 Laravel 13，但 Filament 3.x 最高只支持 Laravel 12。
**解决：**
```bash
# 降级到 Laravel 11
rm -rf demo-app
composer create-project laravel/laravel:^11.0 demo-app --prefer-dist --no-install
```

### Q4：ext-zip 缺失

```
The openssl extension is required for SSL/TLS protection
```

或：
```
Required extension "ext-zip" is missing
```

**解决：**
```bash
# 临时跳过（后续在 php.ini 里启用）
composer require filament/filament:"^3.2" -W --ignore-platform-req=ext-zip
```

### Q5：post-create-project-cmd 脚本报错

```
Warning: require(vendor/autoload.php): Failed to open stream
```

**原因：** 使用了 `--no-install`，vendor 目录还没生成。
**解决：** 手动 `composer install` 后再手动 `php artisan key:generate`

### Q6：Laravel 13 vs 11 的区别

| 版本 | PHP 要求 | Filament 兼容 | 说明 |
|------|---------|--------------|------|
| Laravel 13 | 8.3+ | ❌ 不兼容 | 最新但 Filament 还没适配 |
| Laravel 12 | 8.2+ | ✅ 兼容 | 中间版本 |
| Laravel 11 | 8.2+ | ✅ 完美兼容 | **本项目选择** |
| Laravel 10 | 8.1+ | ✅ 兼容 | 如果你还是 PHP 8.1 |

---

## 五、项目目录结构

```
D:\WorkBuddyDev\laravel-filament/
├── demo-app/                    ← Laravel 11 宿主项目
│   ├── app/
│   │   └── Providers/Filament/
│   │       └── AdminPanelProvider.php  ← Panle 配置
│   ├── config/
│   ├── database/
│   ├── public/
│   ├── resources/
│   ├── routes/
│   ├── .env                     ← 默认 SQLite
│   ├── artisan
│   └── composer.json
│
├── packages/
│   └── raise-engine/            ← RaiseEngine 插件包（待创建）
│
├── docs/                        ← 设计方案文档
└── readme.md                    ← 本文件
```

---

## 六、验证清单

完成安装后跑一遍确认：

```bash
php -v                  # → 8.3.29 ✓
php artisan --version   # → Laravel 11.x ✓
php artisan filament:install --panels  # → 检查 Panel 配置 ✓
php artisan serve       # → 启动 ✓
# 浏览器打开 http://127.0.0.1:8000/admin → 能登录 ✓
```

---

## 七、注意事项（总结）

1. **PHP 版本一定要切到 8.3+**，8.1 装不了 Laravel 11
2. **不要用 Laravel 13**，Filament 3.x 不兼容
3. **安全公告**是 Composer 新特性，开发阶段可直接关掉
4. **`php artisan serve` 慢**是正常的，开发阶段可以用 Laragon 的 Nginx 跑
5. **Composer `-d` 参数**在 Windows CMD 下不能用，要用 `composer config` 替代