本地快速开发指南

本文档将帮助您快速在本地环境中启动和开发 Unicode Framework 项目。

系统要求

在开始之前，请确保您的开发环境满足以下要求：

PHP 要求

PHP >= 8.1
必需的 PHP 扩展：

- pdo - 数据库支持 - pdo_mysql - MySQL 数据库支持 - mbstring - 多字节字符串支持 - json - JSON 处理 - openssl - 加密功能（JWT 认证需要）

可选的 PHP 扩展：

pdo_pgsql

pdo_sqlite

redis

其他工具

Composer - PHP 依赖管理工具
Git - 版本控制（可选）

检查 PHP 版本和扩展

<h1 id="检查-php-版本">检查 PHP 版本</h1>
php -v
<h1 id="检查已安装的扩展">检查已安装的扩展</h1>
php -m
<h1 id="检查特定扩展">检查特定扩展</h1>
php -m | grep pdo
php -m | grep redis

环境准备

1. 克隆项目（如果从 Git 仓库获取）

git clone <repository-url>
cd framework

2. 确保目录权限

确保以下目录具有写入权限：

<h1 id="设置运行时目录权限">设置运行时目录权限</h1>
chmod -R 775 runtime/
chmod -R 775 storage/
chmod -R 775 bootstrap/cache/

安装依赖

1. 安装 Composer 依赖

<h1 id="安装所有依赖包括开发依赖">安装所有依赖（包括开发依赖）</h1>
composer install
<h1 id="或仅安装生产依赖">或仅安装生产依赖</h1>
composer install --no-dev

2. 安装 Node.js 依赖（如果使用 Vue3 功能）

<h1 id="如果项目包含-packagejson-且需要前端资源">如果项目包含 package.json 且需要前端资源</h1>
npm install

配置环境

1. 环境变量配置

框架支持通过环境变量进行配置。您可以通过以下方式设置环境变量：

#### 方式一：使用 .env 文件（推荐）

在项目根目录创建 .env 文件：

<h1 id="如果存在-envexample可以复制它">如果存在 .env.example，可以复制它</h1>
cp .env.example .env

然后编辑 .env 文件，配置必要的环境变量：

<h1 id="应用环境">应用环境</h1>
APP_ENV=local
APP_DEBUG=true
<h1 id="数据库配置">数据库配置</h1>
DB_CONNECTIONS_DEFAULT_HOST=localhost
DB_CONNECTIONS_DEFAULT_DATABASE=your_database
DB_CONNECTIONS_DEFAULT_USERNAME=your_username
DB_CONNECTIONS_DEFAULT_PASSWORD=your_password
DB_CONNECTIONS_DEFAULT_PORT=3306
DB_CONNECTIONS_DEFAULT_CHARSET=utf8mb4
<h1 id="redis-配置可选">Redis 配置（可选）</h1>
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
<h1 id="jwt-配置可选">JWT 配置（可选）</h1>
JWT_SECRET=your-secret-key
JWT_ALGORITHM=HS256
JWT_EXPIRATION=3600

#### 方式二：直接设置系统环境变量

<h1 id="linuxmacos">Linux/macOS</h1>
export APP_ENV=local
export DB_CONNECTIONS_DEFAULT_HOST=localhost
<h1 id="windows">Windows</h1>
set APP_ENV=local
set DB_CONNECTIONS_DEFAULT_HOST=localhost

2. 数据库配置

编辑 config/database.php 文件，配置数据库连接：

return [
    'default' => 'mysql',
    'connections' => [
        'mysql' => [
            'driver' => 'mysql',
            'host' => env('DB_CONNECTIONS_DEFAULT_HOST', 'localhost'),
            'database' => env('DB_CONNECTIONS_DEFAULT_DATABASE', 'mydb'),
            'username' => env('DB_CONNECTIONS_DEFAULT_USERNAME', 'root'),
            'password' => env('DB_CONNECTIONS_DEFAULT_PASSWORD', ''),
            'port' => env('DB_CONNECTIONS_DEFAULT_PORT', 3306),
            'charset' => env('DB_CONNECTIONS_DEFAULT_CHARSET', 'utf8mb4'),
        ],
    ],
];

3. 应用配置

编辑 config/app.php 文件，配置应用基本设置：

return [
    'default_app' => 'index',
    'default_controller' => 'Index',
    'default_action' => 'index',
    'default_response_format' => 'json',
];

启动项目

方式一：使用 Composer 脚本（推荐）

<h1 id="启动开发服务器默认端口-8000">启动开发服务器（默认端口 8000）</h1>
composer serve
<h1 id="或直接使用">或直接使用</h1>
php -S localhost:8000 -t public

服务器启动后，访问：http://localhost:8000

方式二：使用项目提供的启动脚本

<h1 id="使用默认端口-8000">使用默认端口 8000</h1>
./serve
<h1 id="指定端口">指定端口</h1>
./serve 8080
<h1 id="指定端口和主机">指定端口和主机</h1>
./serve 8080 0.0.0.0

方式三：使用 PHP 内置服务器

<h1 id="基本启动">基本启动</h1>
php -S localhost:8000 -t public
<h1 id="指定文档根目录和路由文件">指定文档根目录和路由文件</h1>
php -S localhost:8000 -t public public/index.php

方式四：使用其他 Web 服务器

#### Nginx 配置示例

server {
    listen 80;
    server_name localhost;
    root /path/to/framework/public;
    index index.php;
location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

#### Apache 配置示例

确保启用 mod_rewrite 模块，并在 public 目录下创建 .htaccess 文件：

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ index.php?$query_string [L]
</IfModule>

开发工具

Composer 脚本命令

项目提供了多个便捷的 Composer 脚本：

<h1 id="启动开发服务器">启动开发服务器</h1>
composer serve
<h1 id="运行所有测试">运行所有测试</h1>
composer test
<h1 id="快速测试无覆盖率">快速测试（无覆盖率）</h1>
composer test:quick
<h1 id="生成测试覆盖率报告">生成测试覆盖率报告</h1>
composer test:coverage
<h1 id="运行-api-契约测试">运行 API 契约测试</h1>
composer test:api-contract
<h1 id="测试修改的文件">测试修改的文件</h1>
composer test:modified
<h1 id="代码静态分析phpstan">代码静态分析（PHPStan）</h1>
composer phpstan
<h1 id="生成-phpstan-基线">生成 PHPStan 基线</h1>
composer phpstan-baseline

控制台命令

<h1 id="查看所有可用命令">查看所有可用命令</h1>
php console
<h1 id="生成应用密钥">生成应用密钥</h1>
php console key:generate
<h1 id="运行数据库迁移">运行数据库迁移</h1>
php console migrate
<h1 id="回滚迁移">回滚迁移</h1>
php console migrate:rollback
<h1 id="运行数据库填充">运行数据库填充</h1>
php console db:seed

测试命令

<h1 id="运行所有测试">运行所有测试</h1>
vendor/bin/phpunit
<h1 id="运行特定测试文件">运行特定测试文件</h1>
vendor/bin/phpunit tests/App/AppTest.php
<h1 id="运行特定测试类">运行特定测试类</h1>
vendor/bin/phpunit --filter AppTest
<h1 id="生成覆盖率报告">生成覆盖率报告</h1>
vendor/bin/phpunit --coverage-html coverage/html

PHPStan 代码质量检查

<h1 id="检查整个项目">检查整个项目</h1>
vendor/bin/phpstan analyse
<h1 id="检查单个文件">检查单个文件</h1>
vendor/bin/phpstan analyse --no-interaction --memory-limit=1G src/Auth/JWT.php
<h1 id="仅检查-src-目录">仅检查 src 目录</h1>
find src -type f -name '*.php' | while IFS= read -r f; do
    echo "Analysing $f";
    vendor/bin/phpstan analyse --no-interaction --memory-limit=1G "$f" && continue || {
        echo "Stopped on first error in $f";
        exit 1;
    };
done

开发工作流

1. 创建路由

在 route.php 或 app/{app-name}/route.php 中定义路由：

use Unicode\Framework\Route\Route;
Route::get('/hello', function() {
    return ['message' => 'Hello, Unicode Framework!'];
}, 'hello');

2. 创建控制器

在 app/{app-name}/controller/ 目录下创建控制器：

<?php
namespace App\Index\Controller;
use Unicode\Framework\Http\Request;
class UserController
{
    public function index(Request $request): array
    {
        return ['users' => []];
    }
}

3. 创建模型

在 app/{app-name}/model/ 目录下创建模型：

<?php
namespace App\Index\Model;
use Unicode\Framework\Database\Model;
class User extends Model
{
    protected static string $table = 'users';
    protected static array $fillable = ['name', 'email'];
}

4. 运行数据库迁移

php console migrate

5. 测试您的代码

<h1 id="运行测试">运行测试</h1>
composer test
<h1 id="或运行特定测试">或运行特定测试</h1>
vendor/bin/phpunit tests/App/YourTest.php

常见问题

1. 端口已被占用

问题

解决方案

<h1 id="使用其他端口">使用其他端口</h1>
composer serve -- --port=8080
<h1 id="或使用启动脚本">或使用启动脚本</h1>
./serve 8080

2. 权限错误

问题

解决方案

<h1 id="设置目录权限">设置目录权限</h1>
chmod -R 775 runtime/
chmod -R 775 storage/
chmod -R 775 bootstrap/cache/

3. 数据库连接失败

问题

解决方案

检查数据库服务是否运行：

# MySQL mysql -u root -p

# PostgreSQL psql -U postgres

检查配置文件中的数据库连接信息是否正确
检查防火墙设置
确认数据库用户权限

4. Composer 依赖安装失败

问题

composer install

解决方案

<h1 id="清除-composer-缓存">清除 Composer 缓存</h1>
composer clear-cache
<h1 id="删除-vendor-目录和-composerlock重新安装">删除 vendor 目录和 composer.lock，重新安装</h1>
rm -rf vendor/ composer.lock
composer install

5. 找不到类或函数

问题

解决方案

<h1 id="重新生成自动加载文件">重新生成自动加载文件</h1>
composer dump-autoload
<h1 id="或使用优化版本">或使用优化版本</h1>
composer dump-autoload --optimize

6. 路由不工作

问题

解决方案

检查路由是否正确注册
检查 public/index.php 是否正确加载
检查 Web 服务器配置（如果使用 Nginx/Apache）
清除路由缓存：

   rm -rf bootstrap/cache/routes.php

7. 环境变量不生效

问题

解决方案

确保 .env 文件在项目根目录
检查环境变量名称是否正确（使用下划线分隔，如 DB_CONNECTIONS_DEFAULT_HOST）
重启 Web 服务器或 PHP-FPM
清除配置缓存（如果启用了配置缓存）

下一步

查看 README.md 了解项目概述
查看 docs/ 目录下的详细文档
阅读路由文档了解路由系统
阅读数据库文档了解 ORM 使用
阅读认证文档了解 JWT 认证

获取帮助

如果遇到问题：

查看项目文档：docs/ 目录
检查测试用例：tests/ 目录
查看示例代码：examples/ 目录
提交 Issue 到项目仓库

---

祝您开发愉快！ 🚀