Webman项目必须遵循的Composer使用规范

在Webman项目开发中，Composer的正确使用并非可选，而是确保项目稳定运行的关键。许多开发者遇到的“Class 'WebmanApp' not found”、路由加载失败或插件不生效等问题，其根源往往在于未能遵循Webman框架独特的Composer管理机制。掌握以下规范，能有效避免这些常见陷阱。

为什么 composer create-project webman/webman 会失败或装错

直接执行composer create-project webman/webman命令，通常无法成功创建项目。这是因为官方webman/webman仓库本身是一个空骨架，并未包含标准的composer.json入口或预构建的发行版。Composer执行此命令时，要么直接返回“Could not find package webman/webman”错误，要么会拉取不稳定的dev-master分支，导致项目缺少核心启动文件和正确的自动加载配置。

• Webman框架的官方发布形式是GitHub Releases页面提供的webman-x.x.x.zip压缩包（请注意，这不是源代码包）。
• 解压该zip包后，你将获得一个完整、可直接部署的Webman项目环境，其中已包含正确的composer.json、核心启动文件start.php以及预配置的自动加载映射。
• 同样，应避免使用composer require webman/webman命令。此命令安装的仅是框架组件库，而非完整的应用程序骨架，安装后你会发现项目甚至缺少start.php这个核心入口文件。

安装依赖时必须加 -W 参数

这是Webman项目依赖安装中的一个关键步骤。出于安全策略考虑，Webman默认禁用了部分PHP系统函数（如exec、shell_exec）。然而，许多Composer包（例如Laravel的数据库组件illuminate/database或某些UI库）在安装过程中会尝试调用这些被禁用的函数，从而导致安装过程意外中断或静默失败。

• 正确的安装方式是：执行composer require -W illuminate/database。这里的-W参数（等同于--ignore-platform-reqs）指示Composer忽略平台限制，跳过对禁用PHP函数的检查。
• 安装webman/admin等官方插件时，同样需要附加此参数：composer require -W webman/admin。
• 依赖安装完成后，务必前往config/plugin/目录下验证是否生成了对应的插件配置目录，仅确认vendor/文件夹中存在代码是不够的。

start.php 里的 require_once 链路不能动

此文件是Webman启动机制的核心，也是容易引发问题的关键点。Webman的启动不完全依赖于Composer的自动加载器，而是通过start.php文件顶部一系列硬编码的require_once语句来加载核心类与基础配置。如果你移动了vendor目录、修改了BASE_PATH常量定义，或误删了某行require语句，将立即导致“Class 'WebmanApp' not found”等致命错误。

• 核心原则：切勿手动修改start.php中的路径加载逻辑。尤其要确保__DIR__ . '/vendor/autoload.php'这一行指向的路径绝对准确。
• 若你对项目目录结构进行了调整（例如将Webman置于子目录中），首要任务就是同步更新start.php文件内的BASE_PATH常量以及所有require_once语句的相对路径。
• 一个简单的验证方法：尝试删除vendor/autoload.php文件，然后再次运行php start.php start。如果项目仍能启动，则证明其运行并未依赖Composer的自动加载，而是完全依靠start.php中的手动引用链。

插件配置合并机制依赖 config/plugin/ 目录结构

Webman插件的加载逻辑独具特色。它并非通过Composer的autoload机制来加载插件的业务逻辑，而是通过扫描config/plugin/{vendor}/{name}/这一特定目录结构下的配置文件（例如app.php、route.php），并自动将它们合并到主应用配置中。这意味着：

• 插件必须将其配置文件正确安装到config/plugin/目录下对应的供应商和包名路径中。仅在vendor/目录中存在代码是无法使插件正常工作的。
• 例如，config/plugin/webman/admin/app.php这个配置文件会被框架自动读取并用于注册服务提供者。但如果错误地将其放置在config/plugin/admin/目录下，相关配置将完全失效。
• 插件自身的composer.json中声明的autoload配置，主要作用是在开发阶段为IDE提供代码提示支持，在Webman实际运行时并不生效。真正驱动插件功能的是config/plugin/目录下的那些配置文件。

最后，也是最关键的一点：Webman的Composer使用逻辑是“配置驱动”的，而非纯粹的“类自动加载驱动”。你可能正确修改了composer.json并成功安装了依赖，但如果start.php的加载链路和config/plugin/的目录结构未能正确匹配，那么所有依赖安装工作都将前功尽弃。确保这三者协调一致，是Webman项目依赖管理的核心要义。