CodeIgniter4.7.0教程：官方扩展包集成指南-php教程-PHP中文网

composer安装扩展包必须使用阿里云镜像，配置需满足三要素：键名repo.packagist、类型composer、url末尾带/；shield需手动启用过滤器并初始化管理员；escaper需显式调用；worker mode依赖frankenphp部署。

codeigniter4.7.0教程：官方扩展包集成指南

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) ?> 行为。

CodeIgniter 4.7.0

CodeIgniter下载页提供 CodeIgniter 4.7.0 官方源码包，并整理框架安装、数据库配置与入门开发说明。

下载

它的价值在于提供更细粒度的上下文转义能力，比如 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 就够了，别为了“尝鲜”提前引入复杂部署负担。