Composer安装扩展包必须使用阿里云镜像，配置需满足三要素：键名repo.packagist、类型composer、URL末尾带/；Shield需手动启用过滤器并初始化管理员；Escaper需显式调用；Worker Mode依赖FrankenPHP部署。
Composer 安装扩展包必须走阿里云镜像
国内直接 composer require 几乎必然卡死或超时，不是网络问题，是 packagist.org 域名解析和 CDN 限速导致的。官方扩展包（如 codeigniter4/escaper、codeigniter4/shield）和其他社区包一样，都依赖镜像源才能稳定拉取。
三要素缺一不可：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ —— 键名必须是 repo.packagist（不是 repos.packagist），类型必须显式声明为 composer，URL 末尾必须带 /。漏掉任一，composer config -g repo.packagist 返回 null 或空对象，说明没生效。
- 验证是否生效：运行
composer config -g repo.packagist，正确输出应为{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} - 项目级配置更可靠：进项目目录后执行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/，避免宝塔、Docker 环境下全局配置被忽略 - 安装命令必须加引号：例如
composer require codeigniter4/shield "v4.7.0"，不加双引号会导致版本解析失败
Shield 认证包集成后必须手动启用
codeigniter4/shield 不是装完就自动接管登录流程的“开箱即用”组件。它提供的是可插拔的安全层，需要你显式调用并注入到请求链中，否则所有中间件、过滤器、认证逻辑都不会激活。
关键动作只有两步，但漏掉任一就会出现“明明装了 Shield 却仍能绕过登录”的现象：
- 在
app/Config/Filters.php中把'shield' => \CodeIgniter\Shield\Filters\Auth::class加入$aliases，并确保目标路由组启用了该 alias（比如'before' => ['shield']） - 运行
php spark shield:create-admin初始化管理员账号——这一步会建表、设默认权限、生成初始用户，不执行则数据库为空，登录页永远提示“用户不存在” - 别依赖
spark install:shield的交互式引导：它只复制模板文件，不处理数据库迁移或权限初始化，真正起效靠的是后续的手动命令
Escaper 扩展包不能替代原生 esc() 函数
codeigniter4/escaper 是一个独立的 HTML/XSS 转义工具包，但它和 CI4 内置的 esc() 函数互不感知、不自动集成。装了包 ≠ 自动替换所有输出逻辑，也不会影响视图里已写的 = esc($data) ?> 行为。
它的价值在于提供更细粒度的上下文转义能力，比如 JSON 输出、URL 参数编码、CSS 属性值转义等，但必须显式调用：
- 要使用它，得先在控制器或服务里实例化：
$escaper = service('escaper'); - 然后按需调用：
$escaper->escapeJson($data)、$escaper->escapeUrl($url)，而不是直接改写esc()函数的行为 - 注意命名冲突：如果你自己写了
esc()辅助函数，又引入了这个包，两个esc()可能互相覆盖，建议统一用service('escaper')显式调用
Worker Mode 扩展包需配合 FrankenPHP 部署
php spark worker:install 只是生成 Caddyfile 和入口文件，它本身不提供运行时环境。Worker Mode 是实验性功能，本质是让 CI4 在 FrankenPHP 进程里常驻，而非传统 PHP-FPM 模式下的每次请求重启框架。
这意味着：不部署 FrankenPHP，worker:install 生成的文件毫无作用；部署了但没配好，反而会导致 502 或请求超时。
- 确认服务器已安装 FrankenPHP（不是普通 PHP）：运行
frankenphp version，输出应含frankenphp字样 - Caddyfile 中的
php_server必须指向worker.php入口，且端口不能与现有 Nginx/Apache 冲突 - 静态状态风险：常驻进程下，
static $cache = []类变量会在多次请求间残留，数据库连接不会自动关闭，务必检查所有单例、静态属性、PDO 实例的生命周期
Worker Mode 的性能收益只在真实并发场景下可见，本地开发用 php spark serve 就够了，别为了“尝鲜”提前引入复杂部署负担。
