安装说明
本教程将带你核对运行环境、通过 Composer 创建 Viswoole 项目，并启动第一个 HTTP 服务。全部步骤完成后，你将在 9501 端口看到框架的默认响应。
环境要求
以下要求来自框架 composer.json 的依赖声明：
| 依赖项 | 版本要求 | 说明 |
|---|---|---|
| PHP | >= 8.4 | 框架大量使用 PHP 8.4 特性，版本不能低于此要求 |
| Swoole 扩展 | >= 5.1 | 协程引擎（Coroutine Engine），框架核心依赖 |
| fileinfo 扩展 | * | PHP 内置扩展，用于上传文件类型识别 |
| redis 扩展 | * | PHP Redis 客户端，缓存与 Redis 连接池依赖 |
| pdo 扩展 | * | 数据库访问扩展，通常随 PHP 默认启用 |
| sockets 扩展 | * | PHP 内置扩展，通常随 PHP 默认启用 |
| Composer | 最新稳定版 | PHP 包管理器 |
部署模式说明
Viswoole 基于 Swoole 常驻内存运行，不支持 PHP-FPM / Nginx + Apache 部署模式。服务通过框架内置的 CLI 命令直接启动，Nginx 仅作为反向代理（见 生产环境配置）。
安装 Swoole 扩展
Swoole 是框架的核心运行时依赖。以 pecl 安装为例：
pecl install swoole安装完成后确认 php.ini 中已启用扩展：
extension=swoole.so验证安装结果：
php --ri swoole输出中包含 Version => 5.1.x 或更高版本即安装成功。
替代方案
也可以使用 phpswoole/swoole 官方 Docker 镜像跳过手动编译，详见 容器化部署。
创建项目
使用 Composer 一键创建 Viswoole 应用骨架：
composer create-project viswoole/viswoole myProject该命令会下载 viswoole/framework 核心包及全部依赖，并生成标准的项目目录结构（目录职责详见 项目结构介绍）。
进入项目目录：
cd myProject项目初始化
框架提供了三个初始化命令，用于同步框架资源与依赖包注册信息：
php viswoole vendor:publish # 将依赖包内的配置等资源发布到项目根目录
php viswoole service:discover # 扫描依赖包中的服务提供者并生成注册文件
php viswoole command:discover # 扫描依赖包中的自定义命令并生成注册文件INFO
以上命令通常由项目骨架在 composer install / composer dump-autoload 之后自动触发；如果你是在已有项目中更新依赖，或不确定是否已执行，可再次手动运行以确保同步。
配置环境变量
在项目根目录创建 .env 文件，按需设置环境变量：
; 是否开启调试模式（生产环境必须为 false）
app_debug=true
; 默认时区
default_timezone=Asia/Shanghai
; 数据库连接（对应 config/database.php 中的 env() 调用）
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306.env 的完整格式约定、读取规则与优先级见 环境变量。
安全提示
.env 包含敏感信息（数据库密码等），务必将其加入 .gitignore，不要提交到版本控制系统。
启动服务
前台启动（开发推荐）
php viswoole server:start服务名参数可省略，默认启动 config/server.php 中 default_start_server 指定的服务（默认 http）。启动命令的完整选项：
| 参数/选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| service | string | server.default_start_server（即 http） | 要启动的服务名称，对应 config/server.php 中 servers 的键名 |
-f, --force | 选项 | 无 | 服务已在运行时，先关闭再强制启动 |
-d, --daemonize | 选项 | 无 | 以守护进程（Daemon）方式后台运行 |
验证服务
服务默认监听 0.0.0.0:9501（config/server.php 中定义）。用 curl 请求根路径：
curl http://127.0.0.1:9501/框架默认路由会返回类似 <h1>Hello Viswoole. #4321</h1> 的响应，说明服务已正常运行。
也可以在浏览器直接访问 http://127.0.0.1:9501/。
IDE 支持（可选）
安装 Swoole IDE Helper 获得更好的代码补全与类型提示（框架开发依赖中已使用该包）：
composer require --dev swoole/ide-helper该包仅开发环境使用，不影响生产运行。
更新框架
单独更新 Viswoole 框架核心包：
composer update viswoole/framework更新完成后建议重新执行初始化命令，保持资源与服务注册同步：
php viswoole vendor:publish
php viswoole service:discover
php viswoole command:discover常见问题
提示 ext-swoole 未找到
确认 Swoole 扩展安装在当前 CLI 使用的 PHP 版本中：
php -m | grep swoole注意：CLI 与 FPM 可能使用不同的 php.ini，Swoole 必须在 CLI 环境中可用。
Composer 创建项目缓慢或失败
可配置国内镜像源后重试：
composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/9501 端口被占用
修改 config/server.php 中 servers.http.construct.port 为其他端口后重启服务。