CodeIgniter 4 升级实战:从 4.5.2 升级到 4.5.3 的项目文件变更处理与 composer.json 核对指南
CodeIgniter 4 升级实战:从 4.5.2 升级到 4.5.3 的项目文件变更处理与 composer.json 核对指南
本篇指南以 CodeIgniter 4 官方升级文档(user_guide_src/source/installation/upgrade_453.rst)为主线,系统讲解从 4.5.2 升级到 4.5.3 的完整流程:如何根据你自己的安装方式选择对应的升级命令,为什么「项目空间」(root、app、public、writable)下的文件必须手动合并,以及本次升级唯一发生变更的项目文件 composer.json 应如何处理。读完本文,你将能独立完成 4.5.2 → 4.5.3 的升级、正确合并项目文件,并确认升级结果。
一、版本背景:4.5.3 是一次怎样的发布
CodeIgniter 4.5.3 于 2024 年 6 月 25 日发布(见仓库内 changelogs/CHANGELOG_4.5.md 的 ## [v4.5.3] 条目)。从该版本的修复记录看,这是一次以 Bug 修复为主的小版本发布,不涉及 Breaking Changes(破坏性变更),因此升级风险相对较低,但依然需要按官方流程检查项目文件。
4.5.3 修复的典型问题包括(详见同一文件第 143–156 行):
RedisHandler::deleteMatching()在启用缓存前缀(cache prefix)时无法删除匹配键;DefinedRouteCollector::collect()与spark routes在路由包含正则表达式时抛出BadRequestException/TypeError;migrate:rollback -b因TypeError无法工作;- Validation 规则
if_exist在数组数据上不生效; - Auto Routing Improved 下,默认方法回退(Default Method Fallback)与
$translateUriToCamelCase组合时失效; - 同名
$name命令类的优先级判定错误; command()可能错误执行rewrite.php;- 为 appstarter 的 PSR-4 自动加载补充
Config命名空间(这一点与本文后面要讲的composer.json变更直接相关)。
对应的版本变更文档(user_guide_src/source/changelogs/v4.5.3.rst)中也明确说明:完整的 Bug 修复清单以仓库根目录的 CHANGELOG.md 为准。
二、升级前确认:你当前的 CodeIgniter 版本
动手升级前,先确认你当前运行的确是 4.5.2。官方升级总览(user_guide_src/source/installation/upgrading.rst)给出了两种方式:
- 查看 Debug Toolbar(调试工具栏):开发环境下页面底部会显示当前框架版本;
- 输出版本常量:直接
echo \CodeIgniter\CodeIgniter::CI_VERSION;。
CI_VERSION 常量定义在框架核心类 system/CodeIgniter.php 中(当前仓库开发分支显示为 4.7.6-dev,你项目中的值应为你锁定的发布版本)。确认版本为 4.5.2 后,即可按下一步选择升级路径。
三、按安装方式选择对应的升级路径
官方文档强调:请根据你自己的安装方式,参考对应的升级说明(原文档列出的三个入口分别对应三种典型安装场景)。三种方式及对应入口如下:
1. Composer 安装的 App Starter(新建项目骨架)
如果你最初是通过 composer create-project codeigniter4/appstarter project-root 创建的项目,升级入口见 Composer 安装文档的 App Starter 升级小节。在项目根目录执行:
composer update
执行后需要阅读升级说明与变更日志,检查是否存在 Breaking Changes 与 Enhancements。如果只想升级到指定版本(例如 4.5.3),则先打开项目根目录的 composer.json,将框架版本固定为:
"require": {
"...": "...",
"codeigniter4/framework": "4.5.3"
}
然后运行 composer update。注意:一旦使用固定版本号,composer update 不会再自动升级到更高版本,后续如需升级要手动修改该版本号。
2. Composer 添加到已有项目
如果是在既有应用中通过 composer require codeigniter4/framework 引入框架,升级入口见 Composer 安装文档的「添加到已有项目」升级小节,操作同样是在项目根目录执行:
composer update
需要固定版本时的做法与 App Starter 方式完全一致(修改 composer.json 中的 codeigniter4/framework 版本约束后再 composer update)。
3. 手动安装(不使用 Composer)
如果你采用下载 ZIP 包解压的方式安装,升级入口见 手动安装文档的升级小节。手动安装的升级方式最直接:下载一份新版本框架,然后用新版本替换项目中的 system 文件夹。注意官方明确要求:不要在 system 文件夹内做任何改动,否则升级时你的改动会被直接覆盖。
三种方式在升级上的共同点:框架本体(
system或vendor/codeigniter4/framework/system)会随命令或手动替换自动更新;而项目空间内的文件不会——这正是下一节要讲的核心概念。
四、核心概念:项目空间(Project Space)与 system 作用域
官方升级文档反复强调一个关键区分:项目空间(project space,即 root、app、public、writable 目录)下的文件在每次升级中都可能收到更新,但这些文件位于 system 作用域之外,因此不会被自动修改,必须由你手动干预。
以 Composer 方式为例,composer update 只会更新 vendor/codeigniter4/framework 内的框架代码;位于项目根目录的 app/、public/、writable/ 以及根目录的 composer.json、spark、preload.php 等文件,即使新版本框架中对应的默认文件发生了变化,也不会被覆盖。手动安装同理——替换 system 文件夹后,项目空间的其余文件都需要你自行对照新版框架默认文件进行合并。
因此,一次完整的升级由两部分组成:
- 更新框架本体(系统作用域):Composer 方式用
composer update,手动方式替换system文件夹; - 合并项目空间文件:将你的应用文件与新版本框架提供的默认版本逐一对账,把新版中的修复、弃用标记或格式调整合并进来,同时保留你自己的自定义配置。
官方也提示存在一些第三方 CodeIgniter 模块可辅助合并项目空间的变更(例如在 Packagist 上搜索 codeigniter4 updates 相关包),你可以按需选用,但手动合并依然是官方推荐的基础做法。
五、4.5.2 → 4.5.3 的项目文件变更清单
原文档将项目空间的变更分成两类清单,本次升级的两个清单内容高度集中:
Content Changes(内容变更,建议合并)
这一节列出的是发生了实质性变更(包括弃用调整或视觉调整)、官方建议你合并新版到应用中的文件。4.5.3 的清单只有一项:
composer.json
All Changes(全部变更)
这一节是项目空间内收到过变更的全部文件的完整列表;其中很多可能只是注释或格式调整,不影响运行时行为。4.5.3 的清单同样只有一项:
composer.json
也就是说,4.5.2 → 4.5.3 唯一需要关注的项目空间文件就是根目录的 composer.json,且它同时被列入了「建议合并」清单,说明并非无足轻重的格式调整。
composer.json 具体可能变了什么
结合仓库证据可以进一步推断这次变更的内容。4.5.3 的修复记录中有一条:chore: add Config namespace to appstarter autoload.psr4(为 appstarter 的 PSR-4 自动加载补充 Config 命名空间)。对照仓库中当前 appstarter 的模板 admin/starter/composer.json,其 autoload.psr-4 配置为:
"autoload": {
"psr-4": {
"App\\": "app/",
"Config\\": "app/Config/"
},
...
}
其中 "Config\\": "app/Config/" 正是那一次补充的命名空间映射。由此可以推断:本次项目空间 composer.json 的变更,核心在于 PSR-4 自动加载配置(Config 命名空间)的补充——如果你的应用依赖 Config\ 命名空间下的配置类被自动加载,合并这一变更后需重新生成 Composer 自动加载文件。
六、合并 composer.json 的实操步骤
按官方升级总览(user_guide_src/source/installation/upgrading.rst)的说明,合并项目空间文件的标准做法是对比原文件:
- 找到原始文件:Composer 方式下,新版本的原始
app/Config/App.php等文件位于vendor/codeigniter4/framework/app/Config/App.php(即vendor/codeigniter4/framework目录中);手动方式下,则来自你下载的新版 ZIP 压缩包; - 逐项对比:将
vendor/codeigniter4/framework中的composer.json(或压缩包内的同名文件)与你项目根目录的composer.json对比,找出差异; - 选择性合并:把新版中的变更合并进你自己的文件,同时保留你自己的自定义内容(如项目特有的依赖、脚本、
autoload-dev等); - 或者整体替换:也可以直接用新版文件替换旧的
composer.json,再把你的自定义行加回去——官方明确给出了这一替代方案。
以本次为例,核心要合并的是 autoload.psr-4 中 Config 命名空间的补充;合并完成后,执行:
composer update
让 Composer 根据新的配置重新生成 vendor/autoload.php,使新增的命名空间映射生效。
七、升级完成后的验证
升级并合并完项目文件后,建议按以下顺序验证:
- 确认版本号:再次
echo \CodeIgniter\CodeIgniter::CI_VERSION;或查看 Debug Toolbar,确认框架已变为 4.5.3; - 验证自动加载:确认
Config命名空间下的配置类能被正常加载(例如访问任意一个页面,观察是否出现类找不到错误); - 回归验证修复项:如果你此前曾受 4.5.3 修复列表中的问题影响(如
migrate:rollback -b、带正则的路由、if_exist校验等),可重点回归这些场景; - 生产部署时:按官方建议,部署到生产环境前执行
composer install --no-dev
该命令会移除仅用于开发的 Composer 包,显著缩小 vendor 目录体积(Composer 安装文档对此有明确说明,见 installing_composer.rst)。
结语
从 4.5.2 升级到 4.5.3 是 CodeIgniter 4 一次典型的小版本升级:框架本体由 composer update(或手动替换 system 文件夹)自动更新,而项目空间中唯一发生变更的 composer.json 需要你手动合并——本次的核心是把 Config 命名空间补充进 PSR-4 自动加载配置并重新生成 autoload 文件。只要把握住「系统作用域自动更新、项目空间手动合并」这条原则,后续任何版本的升级都可以照此流程顺利推进。更多升级通用指引可参阅 升级总览文档。