没编译环境、没搞过框架路由的人，第一次在Windows上跑CodeIgniter 4，十有八九会卡在同一道坎上：明明装好了Wamp，下载了框架源码，浏览器一打开却看到一堆目录列表，或者干脆是404。这不是你笨，而是因为CI4的入口结构变了，跟上古时期的CI3完全不同。这篇教程就解决这件事：从Wamp环境准备，到下载CodeIgniter 4，再到第一个Hello World跑通，全程按Windows环境来聊，每一步都说清楚为什么这么做。内容面向刚接触CI4的PHP新手，也适合从CI3升级过来一时半会没转过弯的老伙计。
1. 为什么Windows开发环境首选Wamp套装，版本选型里藏着哪些坑
1.1 Wamp解决的是Windows下PHP环境“装得上还能用”的问题
Windows不像Linux那样自带PHP和MySQL，手动配一套Apache+PHP+MySQL很折腾，而且这三个东西各自版本的兼容性是个深坑。PHP 8配老版Apache可能会报模块加载错误，MySQL新版连接库和PHP扩展又不匹配，折腾半天最后发现是版本搭配的问题。Wamp这类集成环境把Apache、PHP、MySQL/MariaDB打包到一起，装完打开托盘图标就能启动服务，还能在多个PHP版本之间一键切换，对本地开发来说是最省心的选择。
值得说明的是，集成环境不只是“省事”，它最大的价值是提供了一个一致的基线：你在本地跑通的东西，换一台同样配置的电脑也能跑通。团队协作时，大家装同一个Wamp版本，PHP版本保持一致，很多“在我机器上明明没问题”的甩锅现场能少一半。
1.2 CodeIgniter 4对PHP版本有硬指标，别拿老版本硬扛
CodeIgniter 4的官方要求是PHP 7.3.3以上，但我个人强烈建议直接上PHP 8.0或更高。原因很实际：CI4的框架代码对PHP 8的兼容性在持续迭代中越来越好，第三方组件的生态也都在向高版本迁移，你用一个很老的PHP版本，遇到问题去搜索引擎查解决方案，很多答案已经默认你用的是新版本，对不上号反而浪费时间。
Wamp 3.x系列默认带的PHP版本可能偏旧，配套的可选版本也未必全覆盖到PHP 8。如果你装完发现Wamp里只有PHP 5.6/7.0/7.2这种老版本，建议去把更高版本的PHP下载后放进Wamp的php目录，然后在托盘菜单里重新扫描版本。这个过程不难，但要注意下载的PHP必须是配套Apache的线程安全版本（Thread Safe），否则Apache启动时会直接报错。
1.3 Apache和MySQL怎么选：默认推荐就够用
Wamp里集成的Apache版本通常比PHP版本新一点点，这没问题，Apache只是静态文件服务器加转发器，对PHP的支持通过模块实现，版本差异对CI4影响不大。MySQL/MariaDB部分，CI4的数据库驱动默认面向MySQL语法，MariaDB在绝大多数情况下兼容得很好。我的习惯是直接用Wamp默认的MariaDB配置，因为CI4的数据库驱动和标准MySQL API完全兼容，本地开发阶段看不出差异，等部署到线上换成MySQL也不用手改业务代码。
注意：无论你选MySQL还是MariaDB，安装完一定要先看一眼数据库服务是否真的启动了。Wamp托盘图标是绿色才表示所有服务正常，黄色或红色说明有服务没启动，这时候先去解决服务问题，再去折腾框架，否则后面的操作都会建立在空中楼阁上。
2. CodeIgniter 4的安装方式：Composer和手动下载怎么选
2.1 用Composer创建项目，这是最不容易出错的方式
CodeIgniter 4的官方推荐安装方式是Composer：
composer create-project codeigniter4/appstarter ci4app执行后会在当前目录生成一个名为ci4app的完整项目骨架。这种方式最大的好处是自动拉取依赖，vendor目录、autoload机制一次性配好，不需要你手动去处理什么依赖关系。
国内网络环境下，如果composer下载缓慢或反复超时，切换成国内镜像源通常能解决。换源之后，重新执行上面的create-project命令即可。
2.2 手动下载压缩包也能跑，但要注意目录对应关系
如果你完全没有Composer，也可以从官方下载appstarter压缩包，解压到Wamp的www目录下面，效果一样。但手动方式有一个隐藏坑：解压完你可能会漏掉一个步骤——确保vendor目录是完整的。因为appstarter压缩包本身不包含vendor依赖（也可能下载到完整版，要看安装包类型），如果缺少vendor目录，框架的autoload机制会直接罢工，报各种“Class not found”错误。所以手动下载安装后，第一件事是检查目录结构里有没有vendor文件夹，没有就先执行：
composer install2.3 public目录是唯一入口：CI4和CI3最大的架构差异
解压完成后，你会看到这样一个目录结构：
ci4app/ ├── app/ # 应用代码（控制器、模型、视图、配置） ├── public/ # Web根目录（唯一对外入口） ├── vendor/ # 依赖库 ├── writable/ # 缓存、日志、会话数据 ├── .env # 环境配置（默认没有，需复制） └── spark # 命令行工具其中public/index.php是全局唯一的入口文件，这和CI3的根目录index.php直接作为入口完全不同。为什么这样设计？核心是安全隔离：app目录里的配置、控制器、模型代码全部在Web根目录之外，外部请求永远拿不到这些源码文件，只能通过public/index.php这个“门卫”进入框架内部，再由框架路由到指定的控制器。这比直接把源码扔在Web根目录下要安全得多。
2.4 安装完成的标准：看到CI4欢迎页
安装完成后，浏览器访问http://localhost/ci4app/public/，如果出现CodeIgniter 4的官方欢迎页，并且能看到“Welcome to CodeIgniter 4 / The small framework with powerful tools”之类的内容，说明环境基本没问题了。这一步跑通，你的PHP版本、Apache、框架文件三者的联动就正常了，后面的事情才谈得上。
3. Wamp侧三个关键开关：Rewrite、PHP扩展、.env配置
3.1 启用mod_rewrite：没有它，路由全部404
CodeIgniter 4默认使用友好URL，也就是http://localhost/ci4app/public/hello这样的地址，而不是index.php?/hello。实现这个效果的前提是Apache的mod_rewrite模块处于激活状态，并且在虚拟主机或目录配置中放行了.htaccess。
Wamp托盘菜单里依次找到：Apache -> Apache modules -> rewrite_module，确保它处于勾选状态。改完之后必须重启Apache，否则不生效。
然后还有一个容易被忽略的点：httpd.conf里对项目目录的AllowOverride配置必须是All。很多人rewrite_module也开了，但AllowOverride是None，Apache会直接无视.htaccess文件里的规则，路由自然404。在Wamp的httpd.conf中搜一下项目对应的Directory段，确认是：
<Directory "C:/wamp64/www/ci4app/public"> AllowOverride All Require all granted </Directory>3.2 开启intl和mbstring扩展：CI4的硬性依赖
CodeIgniter 4要求PHP至少启用intl扩展，这是一个处理国际化相关的扩展，框架的字符串处理、日期格式化底层会用到。Wamp里启用扩展的方法是：托盘图标 -> PHP -> PHP extensions -> php_intl，打勾后重启PHP服务。
另外建议把mbstring扩展也打开。虽然CI4核心不一定强制它，但很多辅助函数和第三方库都依赖多字节字符串支持，不开的话，处理中文内容时可能出现截断或异常。这两个扩展在Wamp里都是点一下的事，但很多人装完CI4只看版本不看扩展，结果一跑起来就报错，回头排查才发现是扩展没开，特别浪费时间。
3.3 复制.env文件并切换到development模式
CI4项目根目录下有一份.env.example文件（有的版本叫env），你要做的是把它复制一份，重命名为.env。这个文件是环境配置的核心，里面可以设置数据库连接、加密密钥、日志级别等。
初次开发阶段，至少要把这一项改掉：
CI_ENVIRONMENT = developmentdevelopment模式会让CI4显示详细的错误日志和调试工具栏，这对定位问题非常重要。如果你是新手，千万不要在没调通之前就保持production模式，否则出了错只能看到一个干巴巴的500页面，连报什么错都不知道，排查难度直接翻倍。
3.4 用虚拟主机把站点根目录指向public
虽然这一节标题是“三个开关”，但虚拟主机配置是让访问URL变干净的关键一步。很多人访问CI4用的是http://localhost/ci4app/public/这个长URL，虽然能用，但你如果想让URL变成http://ci4app.test/这种清爽的地址，就需要配置虚拟主机。
在Wamp的Apache配置目录下，找到httpd-vhosts.conf，添加如下配置：
<VirtualHost *:80> DocumentRoot "C:/wamp64/www/ci4app/public" ServerName ci4app.test <Directory "C:/wamp64/www/ci4app/public"> Options Indexes FollowSymLinks AllowOverride All Require all granted </Directory> </VirtualHost>然后在C:/Windows/System32/drivers/etc/hosts文件里加一行映射：
127.0.0.1 ci4app.test改完重启Apache，直接访问http://ci4app.test/，你会发现URL里不用再带public目录了，因为DocumentRoot已经指到了public。这一步做完，开发体验会舒服很多，而且更贴近线上部署的真实形态。
4. 写一个真正的Hello World：控制器、路由、视图三步走
4.1 第一步：创建一个控制器
在app/Controllers目录下新建一个文件Hello.php。注意两点：文件名首字母必须大写，类名也必须与文件名完全一致，这是CI4遵循PSR-4自动加载规范的基本要求，大小写错了类就找不到。
<?php namespace App\Controllers; use CodeIgniter\Controller; class Hello extends Controller { public function index() { return view('hello'); } }我在这个控制器里让index方法直接渲染一个视图，这是最简单的用法。你可能会注意到方法名叫index而不是其他名字，因为在CI4的默认路由规则里，访问http://ci4app.test/index.php/hello这个地址时，如果URL中没有指定方法名，框架会默认调用控制器的index方法。这算是一个约定优于配置的设计。
4.2 第二步：注册路由
CI4的路由文件在app/Config/Routes.php。打开这个文件，找到$routes->get('/', 'Home::index');这行，在它下面新增一行：
$routes->get('hello', 'Hello::index');这行代码的含义是：当用户访问hello这个URL时，交给Hello控制器的index方法处理。$routes->get表示只匹配HTTP GET请求，如果你还想支持POST之类的请求方式，需要额外定义，不过本教程第一个页面只需要GET就足够了。
为什么不靠默认规则直接访问/hello/还要手动注册呢？因为CI4的默认路由只自动映射到Home控制器，其他控制器必须显式声明路由规则才能被访问。这是CI4和CI3在路由设计上的一个区别，CI3可以靠默认路径猜控制器和方法，CI4更倾向于把路由显式写清楚，这样代码的可读性和可控性更强。
4.3 第三步：创建视图文件
在app/Views目录下新建文件hello.php，写入：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>Hello CI4</title> </head> <body> <h1>Hello World!</h1> <p>欢迎使用CodeIgniter 4，你的第一个页面已经跑通了。</p> <p>框架版本：<?= \CodeIgniter\CodeIgniter::CI_VERSION ?></p> </body> </html>这里我用\CodeIgniter\CodeIgniter::CI_VERSION直接输出框架版本号，目的是顺便验证PHP解析是否正常，如果这里能显示出版本号，说明整个链路从Apache到PHP到CI4全都通了。
4.4 三种访问方式的区别和测试
现在你至少有三种方式来访问这个Hello页面：
| 访问URL | 效果 |
|---|---|
http://ci4app.test/ | 显示CI4默认欢迎页，不是你的hello视图 |
http://ci4app.test/hello | 显示Hello World页面，这是路由生效的效果 |
http://ci4app.test/index.php/hello | 也能显示Hello World，但URL带了index.php |
这三种访问方式我都建议你实际各点一遍。看到第二种方式能正常出内容，说明mod_rewrite和.htaccess的工作链路是健康的；第三种方式虽然不美观，但它是Apache环境在没有开启rewrite时的兜底方案，用来验证“框架本身没问题，只是URL美化配置的问题”。
4.5 顺手验证一下调试工具栏
在development模式下，页面底部会出现CI4的调试工具栏（Debug Toolbar），上面有请求耗时、内存占用、数据库查询等信息。第一次看到它可能觉得碍眼，其实很实用。比如你写了一个查询很慢的接口，它能直接告诉你SQL语句执行了多少毫秒。第一次跑通Hello World时，看到调试工具栏出现，基本可以确认开发环境是健康的。
5. 我的踩坑记录：四个典型症状和完整排查思路
5.1 对照表：遇到问题先按表查
| 症状 | 原因 | 解决办法 |
|---|---|---|
| 浏览器打开显示目录文件列表 | 站点根目录没指向public | 虚拟主机DocumentRoot改为public |
| 403 Forbidden | Apache配置没允许访问目录 | 在Directory段加Require all granted |
| 首页能开，子路由404 | mod_rewrite未启用或AllowOverride为None | 检查rewrite_module和AllowOverride All |
| 白屏或500错误 | PHP扩展缺失或.env未配置 | 开启intl扩展，复制.env并设置development |
| 类找不到的报错 | vendor目录缺失 | 执行composer install |
5.2 完整排查链路：以“首页能开但子路由404”为例
这是我第一次配置CI4时踩的坑，这里把排查思路完整走一遍。
首先浏览器访问http://ci4app.test/hello，显示404。第一反应不是去改代码，而是确认路由是否注册。打开Routes.php，确认$routes->get('hello', 'Hello::index');已经写上，并且Controller文件名和类名都没有拼错。仍然404，排除代码问题。
接下来看Apache错误日志。在Wamp托盘菜单里点击“Apache -> Apache error log”，查看最新的日志记录。如果看到类似“File does not exist”的提示，说明请求确实到了Apache，但没有找到对应的物理文件。这正是index.php入口没有介入的迹象，说明rewrite规则没有生效。
回到配置层面，先检查rewrite_module是否勾选，接着检查虚拟主机配置里AllowOverride是不是All。我把AllowOverride从None改成All，重启Apache，再次刷新，页面正常了。整个排查过程的关键是：不要猜，先看日志，日志会告诉你问题发生在哪一层。
5.3 Windows下.htaccess文件的“隐形坑”
Windows资源管理器默认不显示以点开头的文件，很多时候你从压缩包解压出来，.htaccess是真实存在的，但它在文件管理器里不出现，导致有人误以为CI4没有自带这个文件，自己又乱建了一个。其实只要在代码编辑器（比如某些主流编辑器）的目录树里就能看到.htaccess，不用在资源管理器里死磕。如果发现某个文件叫htaccess.txt或_htaccess，手动重命名为.htaccess即可，重命名时Windows可能弹窗提示“必须键入文件名”，把文件扩展名显示打开再改就好。
5.4 环境切换和线上部署的提醒
本地能跑通的Hello World，部署到线上Linux服务器时大概率还会遇到两个差异点：一是线上Apache的rewrite模块和虚拟主机配置方式不同，二是Nginx环境根本没有.htaccess概念，需要在Nginx配置里写对应的location规则。不过那是后话，教程第1篇先不展开。
你在Windows本地把这个Hello World链路完整走通一遍，最大的收获不是“把页面显示出来了”，而是把“Apache入口配置、PHP扩展依赖、框架路由机制、视图渲染流程”这四件事串成了一条线。之后换到任何环境，只要对照这条线去检查，都能快速定位问题。
如果你也准备开始用CodeIgniter 4做实际项目，我的建议是：先别急着写业务代码，拿一个晚上把本篇教程的整个流程从零再做一遍，包括删掉项目重新安装一次。第一遍我估计你会卡在public目录或者rewrite模块上，第二遍就会顺畅很多。下一次我打算接着写数据库配置和用户注册这种带实际业务逻辑的功能，到时候再填坑。
