CI4环境搭建：WampServer+Composer跑通Hello World

CodeIgniter 4 环境搭建笔记WampServer CI4 跑通 Hello World刚接触 CodeIgniter 4 的朋友最容易在第一道坎上卡住——不是说 PHP 有多难而是框架跑起来的姿势跟老版本差太多了。CI3 时代扔到 www 目录就能跑CI4 却要处理 public 目录、Composer 依赖、intl 扩展、.env 配置……没经验的话光看报错就能劝退一大半新手。我这次把从零开始在 Windows 上搭 CI4 的完整过程记录一下用的是 WampServer 套件目标是让一个 Hello World 页面稳定跑起来。这篇适合三类人刚学 PHP 想直接上框架的、从 CI3 迁到 CI4 的老开发者、以及买了 VPS 想本地先练手的同学。内容会涉及 PHP 版本选择、扩展开关、Composer 安装、项目配置和常见 404 排查全部都是我实际踩过一遍的步骤跟着做基本不会翻车。1. 环境准备WampServer 与 CI4 的前置条件1.1 WampServer 是什么为什么要用它WampServer 是 Windows 平台上一键集成 Apache、MySQL、PHP 的环境包装上之后三个核心服务全都有了省去各自安装配置的痛苦。CI4 其实只需要一个合格的 PHP 环境就能跑理论上用 php 内置开发服务器也能启动但用 WampServer 有一个明显的好处它提供了接近生产环境的 Apache 托管方式后续学路由、伪静态、虚拟主机配置都在同一套环境里完成不用来回切换工具。还有个现实原因——很多新手第一次接触的是集成环境WampServer 的图形界面可以直观看到 PHP 版本切换和扩展开关状态排查环境问题比纯命令行友好太多。装好之后系统托盘会出现一个半圆图标左键点击能看到 Apache、MySQL、PHP 的管理菜单。1.2 PHP 版本与必须开启的扩展CI4 官方对 PHP 版本有硬性要求历史版本要求 7.3新版本则建议 8.0 以上。我在实际使用中推荐直接用 PHP 8.1 或 8.2因为框架后续迭代会越来越依赖 PHP 8 的特性你现在用老版本过几个月升级框架就会发现环境跟不上。WampServer 安装完成后默认可能启用某个 PHP 版本你可以通过左键托盘图标选择 PHP - Version 切换版本。切换后最好等 Apache 服务自动重启或者手动点击 Restart All Services。除了版本扩展开关是更隐蔽的问题。CI4 启动时如果缺少 intl 扩展会直接报错intl extension is not installed这一步卡住过很多人。intl 是 ICU 国际化库的 PHP 封装CI4 内部的文本处理、编码转换、URL 解析都会用到它。WampServer 的扩展管理在左键菜单里选 PHP - PHP Extensions勾选 intl 即可也可以在主面板的 php.ini 里搜索extensionintl取消注释并保存。注意修改 php.ini 之后必须重启 Apache否则配置不会生效。另外开启扩展时注意 PHP 版本要对应WampServer 每个 PHP 版本都有独立的 php.ini 文件。mbstring 扩展也是推荐开启的CI4 在处理多字节字符串时依赖它尤其是中文内容。虽然现在 mbstring 在多数 Linux 发行版里默认带了但 Windows 下 WampServer 不一定默认开启同一套扩展组合检查一下最保险。1.3 安装 WampServer 的细节安装包从官方站点下载即可选择 64 位版本注意安装路径不要带中文和空格推荐D:\wamp64。安装过程中可能需要安装 Visual C 运行库按提示确认或等它自动安装这个缺了会导致 Apache 启动不起来。安装完成后会提示设置默认浏览器和文本编辑器可以跳过。启动 WampServer托盘图标从红色变成橙色再变成绿色才算服务全部正常。绿色图标亮起之前前端页面是不可用的。我遇到过一个非常迷惑的情况托盘图标显示绿色但浏览器访问 localhost 仍然打不开。后来发现是系统防火墙拦截了 Apache 的网络通信安装过程中弹窗时选取消后面上网就授不到端口。解决办法是防火墙设置里放行 Apache 进程或者重新安装时选择允许访问。2. 获取 CodeIgniter 4两种安装方式对比2.1 方式一Composer 安装推荐CI4 官方的安装方式首选 Composer因为后续升级框架补丁、安装第三方库全靠它管理比手动下载 ZIP 包方便太多。Windows 上安装 Composer 直接下载安装包一路下一步就行但安装过程中如果遇到 PHP 路径识别不了要先确保 WampServer 的 PHP 已启用。命令行进入你的站点根目录执行composer create-project codeigniter4/appstarter ci4demo命令的含义是用 CodeIgniter 4 的启动项目模板创建一个叫 ci4demo 的目录并自动下载框架核心依赖。如果网络环境导致下载缓慢可以配置一个国内镜像源命令格式如下具体地址以你选择的镜像站官方文档为准composer config -g repo.packagist composer https://镜像站域名/composer配置完再执行 create-project 就会快很多。创建完成后ci4demo 目录结构是官方标准布局重点记住这几个app/应用代码控制器、模型、视图全部在这里public/唯一对外可见的入口目录Apache 应该指向这里writable/缓存、日志、会话文件写入位置.env环境配置文件安装后需要从 env 复制vendor/Composer 依赖目录很多新手的第一反应是把项目放到 WampServer 的 www 目录下然后直接访问http://localhost/ci4demo/结果看到的是目录列表或者 404。原因就是 CI4 的入口不在项目根目录而在public子目录里。正确访问地址是http://localhost/ci4demo/public/。2.2 方式二ZIP 直接下载如果不想装 Composer也可以直接从框架源码仓库下载 ZIP 包解压后同样是 appstarter 结构。这种方式的好处是快缺点是后续框架升级你得手动替换文件而且无法使用代码库托管平台自动拉取依赖。以我个人的经验除非你只是临时看一下代码结构否则还是老老实实用 Composer。就算你项目最终不依赖任何第三方库Composer 管理框架版本这件事本身就值回安装成本。2.3 项目放在哪个目录、怎么访问WampServer 默认站点目录是安装目录下的www文件夹。把项目放在D:\wamp64\www\ci4demo后访问地址就是http://localhost/ci4demo/public/。如果想省略 public可以通过 Apache 虚拟主机把站点根目录指向 public 子目录或者调整 DocumentRoot。但对于刚起步的学习阶段我建议先带着 public 用理解入口文件的概念之后再做精简否则一轮配置下来你可能分不清问题出在环境还是路由。3. 配置与起步第一个 Hello World3.1 配置 env 变量开发环境与 baseURLCI4 安装后根目录有一个env文件它本质上是环境配置模板。你需要复制一份并重命名为.envWindows 下直接在资源管理器重命名可能会碰到隐藏扩展名的问题我习惯用命令行操作copy env .env然后编辑.env至少要改两处。第一处是环境模式去掉CI_ENVIRONMENT前的分号注释并设置为 developmentCI_ENVIRONMENT development这样框架会把错误信息完整显示在页面上方便调试。生产环境遇到同样配置会暴露潜在安全问题但现在是本地学习不追求这个。第二处是app.baseURL先找到app.baseURL 改成你的实际访问地址比如app.baseURL http://localhost:8080/注意要带结尾斜杠。如果你用的是 Apache 方式访问http://localhost/ci4demo/public/也可以直接写这个完整地址。baseURL 的作用是让框架在生成链接、重定向时知道主路径配置错会导致 CSS 加载失败、跳转 404 等一系列连锁问题。提醒改了 .env 之后如果没生效检查三点文件名是否多了.txt后缀、保存编码是否为 UTF-8 无 BOM、是否忘记重启 Apache。开发模式下环境变量缓存有时会拖后腿重启一次解决一切问题。3.2 启动方式Apache 访问与 php spark serveCI4 自带一个开发服务器命令叫php spark serve默认监听 8080 端口。使用前需要确保命令行能识别php命令或者直接用 WampServer 的绝对路径。例如项目目录下执行d:\wamp64\bin\php\php8.1.0\php.exe vendor/bin/spark但每次敲全路径很痛苦建议把 PHP 目录加到系统 PATH 环境变量里。添加之后直接php spark serve浏览器访问http://localhost:8080。另一个方式就是走 Apache浏览器直接访问http://localhost/ci4demo/public/。两种方式的区别在于Apache 更接近真实部署场景需要理解入口和伪静态规则spark serve 适合快速调试改动代码即时生效不需要频繁重启服务。我个人的选择是日常开发用 spark serve因为启动快、日志在终端里很直观等到需要模拟真实环境或配置域名绑定的时候再切换到 Apache。3.3 控制器与视图从 index 到 hello 函数默认首页显示的内容来自app/Controllers/Home.php打开看会发现 Home 控制器下有一个 index 方法内容就是加载一个欢迎视图。我们先做一个最简单的修改直接改 Home 的 index 方法先摸清整个加载链路。?php namespace App\Controllers; class Home extends BaseController { public function index() { return Hello World from CodeIgniter 4!; } }保存后刷新页面如果一切正常你会在浏览器里看到这串字符串。这证明环境没问题框架能执行控制器方法了。但这么直接返回字符串不算正规用法MVC 模式里控制器应该把数据交给视图去渲染。我建议你新建一个专门的控制器来体验完整流程。创建app/Controllers/Hello.php?php namespace App\Controllers; class Hello extends BaseController { public function index() { return view(hello); } }同目录下创建视图文件app/Views/hello.php!DOCTYPE html html langzh-CN head meta charsetUTF-8 title我的第一个 CI4 页面/title /head body h1Hello, CodeIgniter 4!/h1 p如果你看到这行字说明环境和框架都跑通了。/p /body /html访问http://localhost:8080/hello或者 Apache 方式访问http://localhost/ci4demo/public/hello就会看到页面了。3.4 视图里输出变量体验数据流光输出静态 HTML 没什么意思MVC 的核心在于数据从控制器流向视图。修改 Hello 控制器?php namespace App\Controllers; class Hello extends BaseController { public function index() { $data [ title 欢迎, message 这条消息是从控制器传到视图的, ]; return view(hello, $data); } }修改视图文件用 PHP 短标签输出数据!DOCTYPE html html langzh-CN head meta charsetUTF-8 title? esc($title) ?/title /head body h1? esc($message) ?/h1 /body /htmlesc()是 CI4 自带的 HTML 转义函数所有动态数据输出到页面前都应该包一层它防止 XSS 注入。这算是写 CI4 之后刻进肌肉记忆的习惯。4. 路由机制理解 URL 如何找到你的代码4.1 默认自动路由的工作流程访问/hello时CI4 内部把 URL 拆成了几段默认情况下第一段是控制器名第二段是方法名后面的段是参数。这就是控制器、方法、参数的映射关系。URL 片段对应内容/hello控制器 Hello/hello/index控制器 Hello 的方法 index/hello/show/1控制器 Hello 的方法 show参数为 1这种自动映射机制在 CI4 中叫做自动路由约定优于配置新手阶段非常友好。你不需要写任何路由规则就能访问新控制器。但你迟早会遇到需要自定义路由的场景——比如想让 URL 变成更友好的人话形式或者在控制器里对参数做校验。路由定义集中在app/Config/Routes.php文件里。4.2 自定义路由让 Hello World 更实用光靠自动路由不够用我演示一个加参数的路由写法。希望访问/hello/名字的时候页面能打出“你好某某”。首先在app/Config/Routes.php的默认规则之前加一行$routes-get(hello/(:any), Hello::sayHello/$1);然后在 Hello 控制器里添加方法?php namespace App\Controllers; class Hello extends BaseController { public function index() { return view(hello); } public function sayHello($name null) { if ($name null) { return 请提供参数例如 /hello/小明; } return 你好{$name}; } }访问http://localhost:8080/hello/小明可以看到输出。(:any)是 CI4 路由中的占位符匹配任意非斜杠字符捕获到的值作为参数传给$1再拼进方法调用字符串中。这个方法对于列表页分页、详情页跳转、搜索关键词传递都很实用算是 CI4 路由的标配用法。4.3 为什么容易碰到 404环境正常但页面 404大概率是下面几种情况文件没放在app/Controllers目录命名空间不是App\Controllers或者基础命名空间配置被改过类名大小写不对CI4 的控制器类名要求跟文件名一致且首字母大写自动路由被关闭但访问的 URL 又没在 Routes.php 里定义方法名是私有方法或者以_开头框架不允许直接通过 URL 访问排查顺序建议先看Routes.php有没有意外改动再检查控制器的命名空间和类名大小写最后确认文件名。5. 常见坑与排查速查实操过程中遇到的报错很多不是我上面提到的那几类而是和环境、扩展、路径相关的。我整理了一个速查表基本上覆盖了新手第一次启动 CI4 时能遇到的 90% 的问题。症状原因解决办法页面直接显示 PHP 源代码Apache 未启用 PHP 模块或 PHP 处理程序未关联从托盘菜单检查 Apache - PHP 模块是否加载重启服务报错 intl extension is not installedPHP 的 intl 扩展未开启WampServer 菜单中勾选 PHP 扩展 intl重启 Apache首页是目录列表看不到页面内容访问了项目根目录而非 public 目录改成访问http://localhost/ci4demo/public/修改 .env 不生效文件名错误、有 BOM 头、服务未重启用命令行copy env .env重新生成文件重启 Apache访问 /hello 出现 404控制器命名空间不对、文件名大小写错、路由冲突检查命名空间是否为App\Controllers类名首字母大写spark serve 命令报“不是内部或外部命令”PHP 未加入系统 PATH将 PHP 目录加入环境变量 PATH或改用完整路径样式加载 404baseURL 配置错误导致资源定位失败修正 .env 中的 app.baseURL确保以斜杠结尾页面显示错误但不详细CI_ENVIRONMENT 不是 development 或未开启 display_errors.env 设置CI_ENVIRONMENT development重启还有一个容易忽略的细节Windows 下如果你用记事本编辑.env和 PHP 文件保存时默认编码可能是 UTF-8 带 BOMBOM 会让框架在输出 HTML 前输出看不见的字符导致 API 返回 json 数据时解析失败。我的习惯是编辑器统一设置 UTF-8 无 BOM或者用专业编辑器打开文件。另外CI4 的缓存机制在调试时很反直觉。如果你改了控制器或路由但页面没变化先确认writable/cache目录中没有旧缓存文件开发模式下执行一遍php spark clear命令可以清理缓存。6. 目录结构重点与下一步学习路线6.1 从 Hello 到实用熟悉 app 目录跑通 Hello World 只是第一步接下来写真实应用你离不开app目录下的几个核心子目录。我把常用目录的作用列出来目录作用app/Config全局配置路由、数据库、缓存、邮箱等都在这里app/Controllers控制器接收请求、调用业务逻辑app/Models模型和数据表打交道app/Views视图前端模板文件app/Helpers自定义辅助函数app/Filters过滤器用于请求前后拦截处理app/Database数据库迁移和种子数据文件新手最容易犯的错误是把业务逻辑全塞进控制器视图里又写一堆 SQL。CI4 的模板引擎和数据库查询构造器都做得比较完善建议从一开始就养成控制器调模型、模型查数据库、控制器传数据给视图的习惯。6.2 下一步连接 MySQL 做持久化既然装的是 WampServerMySQL 已经在手边了。下一阶段可以从数据模型入手创建一张数据表用 CI4 的查询构造器读写数据再通过表单把数据写进去、在列表页展示出来。这一步能串起 MVC 的完整链路也算真正入门 PHP 框架开发。我自己最开始学 CI4 的时候就是跳过数据库直接学认证和缓存结果回头补模型层时浪费了不少时间。建议按顺序来环境 - 路由 - 控制器 - 视图 - 模型 - 数据库每一步都跑通再往下走稳扎稳打。最后再分享一个小技巧如果你用 spark serve 启动开发服务器可以加--host参数指定监听地址比如php spark serve --host 192.168.1.100这样同一局域网里的其他设备也能访问你的项目方便联调。不过仅限本地局域网调试别暴露到公网安全问题不是一句两句能说清楚的。