简介ThinkPHP6框架完整项目包面向需要入门PHP框架或快速搭建Web应用的中级开发者也适合已有简单PHP基础、希望了解完整工程结构的读者。基于PHP7.1的轻量级MVC架构覆盖依赖管理、配置加载、路由映射、视图渲染、扩展类库等核心模块适合作为本地源码参考与二次开发起点。压缩包共594个文件大小约807KB以479个PHP源码文件为主体同时包含md说明文档、json配置文件、yml持续集成脚本、stub类型定义、sql数据库脚本、env环境变量示例等工程文件目录层级清晰便于定位。已有1246人学习下载。通过整体梳理项目结构可以理解从Composer依赖安装、环境配置、路由定义到控制器与模型实现的一套完整流程也能看到第三方库管理、持续集成配置及应用扩展等实际工程做法有助于快速建立对现代PHP项目结构的整体认知并为后续独立开发PHP项目打下基础。1. thinkphp6框架下载这不是一个“下载完就能跑”的事先讲个身边常见的场景某开发者从官网下了 ThinkPHP 6 的压缩包解压后放在站点目录访问首页直接白屏连错误提示都没有。他折腾了两个小时最后才发现自己下的是 GitHub 上的源码包里面根本没有vendor目录依赖一个都没装。这是我在本地帮人排查过最多次的“下载翻车”现场。所以你搜到“thinkphp6框架下载”这个词时真正要解决的问题不是“把文件拿到手”而是“用正确的方式拿到一份能直接跑起来的框架”。ThinkPHP 6 从 2020 年发布后就一直建议通过 Composer 安装而不是靠浏览器下载压缩包。这篇文章会讲清楚三种下载方式的区别、环境前提、目录结构以及我在真实项目里踩过的那些坑保证你照着做能少走弯路。2. 下载前必须确认的两个前提PHP 版本与 Composer 源2.1 PHP 版本检查为什么 7.2 会被直接拒绝ThinkPHP 6 对 PHP 版本有硬性要求低于 7.2.5 连安装脚本都不会执行。我在实际项目里见过有人在 7.1 的老环境上硬跑 TP6报错信息是一串诡异的语法错误因为框架代码里用了高版本才有的语法特性。检查版本很简单命令行执行php -v如果输出里显示的是PHP 7.2.5及以上版本基本没问题。我还建议同时检查几个必须的扩展php -m | grep -E pdo|mbstring|openssl|json|curl这里php -m会列出所有已加载的扩展grep用来筛选我们需要的那几个。TP6 的数据库操作依赖 PDO文件上传和 HTTP 请求依赖 curl加密相关的功能依赖 opensslmbstring 则影响字符串处理。缺任何一个框架可能装上了但部分功能跑不了。常见做法是缺什么装什么在 Linux 上用apt install php-mbstring或yum install php-openssl这类的命令补上装完记得重启 PHP 服务。2.2 设置 Composer 镜像国内下载不卡死的唯一办法ThinkPHP 6 官方推荐的安装方式是 Composer但我们国内网络拉取 GitHub 和 Packagist 的元数据经常超时。我印象很深的是有一次执行composer create-project卡在Loading composer repositories这一步十几分钟不动最后直接超时失败。后来我把镜像源切到国内镜像整个过程从十几分钟缩短到两分钟。设置方法是全局修改 Composer 配置composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/这行命令让 Composer 从国内镜像拉取包信息而不是直接连接 Packagist 官网。-g表示全局生效不影响单个项目后面那串 URL 换成其他国内镜像也可以但阿里云这个我用下来最稳定。设置完成后可以执行composer config -g -l查看当前生效的配置确认repo.packagist那一项已经变成镜像地址这样就放心了。2.3 环境判断的一个常见误杀PHP 版本没问题却装不上有时候版本检查和扩展检查都通过了composer create-project依然报错。我在某公司帮忙部署时遇到过一种情况PHP 命令行版本和 Web 服务使用的 PHP 版本不是同一个。php -v显示 8.1但apache或nginx加载的是另一个路径下的 PHP 7.4。这种情况在 Windows 上尤其常见因为环境变量里的 PHP 和集成面板里的 PHP 是两套。排查方法是在项目根目录创建一个测试文件用浏览器访问看phpinfo()显示的版本和命令行是否一致。不一致时要让命令行 PHP 切换到和 Web 服务同一套版本否则 Composer 装完后项目运行还是报错这个坑非常隐蔽。3. 用 Composer 下载 ThinkPHP 6正式项目与开发版两条命令3.1 正式项目推荐create-project 命令的完整用法这是官方最推荐的方式也是我每次开新项目必用的命令。它做的不只是“下载代码”还会自动把vendor目录里的依赖全部装好同时触发框架自带的安装程序。整个命令如下composer create-project topthink/think tp6拆开来看create-project是 Composer 的一个特殊命令相当于先执行git clone再自动执行composer install。topthink/think是 ThinkPHP 6 框架在 Packagist 上的包名tp6是项目目录名你可以改成任意合法的目录名。执行过程中你会在终端看到类似Installing dependencies from lock file的进度等它跑完进入tp6目录执行php think run框架就能起一个内置的开发服务器。这是最适合正式项目的安装方式因为它生成的项目里自带.git目录吗不会。create-project下载的源码包不带.git历史记录这对大部分业务项目来说是好事你可以直接git init开一个新仓库不会带入框架本身的提交历史。命令执行时也可以指定版本composer create-project topthink/think tp6 6.1.0末尾那个6.1.0指定安装具体版本。如果不填默认拉取当前最新稳定版。我一般不在生产环境追最新如果团队有固定基线版本就用这个方式锁死版本避免某个小版本升级带来不可控的行为变化。3.2 开发版或二次开发用 git clone 拿到完整仓库如果你要做框架本身的二次开发或者想研究 TP6 内核源码create-project就不太合适了因为它拿到的是裁剪过的项目骨架。这时候我一般会直接从代码托管平台克隆完整仓库git clone https://github.com/top-think/think tp6-dev克隆完成后进入目录手动安装依赖cd tp6-dev composer install这里的逻辑和create-project的区别在于git clone拿到的是完整仓库里面包含框架的全部历史提交、分支信息和测试代码composer install会根据仓库里已有的composer.lock文件安装精确版本的依赖。这个方式适合想给框架提代码贡献的人或者需要调试框架底层逻辑的场景。要注意的是克隆下来的框架默认可能不是 6.x 的最新版本需要自己切换分支git checkout 6.16.1是分支名切换前建议先执行git branch -a查看所有远程分支确认目标分支确实存在。这种方式不适合拿来直接做业务项目因为仓库里有大量和业务无关的文件还容易在后续composer update时把框架核心代码升级到一个超出预期的版本。3.3 两种方式的结果都一样vendor 目录才是灵魂不管是create-project还是git clone加composer install最终项目根目录下都会多出一个vendor文件夹。这个文件夹里存放的是所有第三方依赖包括 TP6 的核心框架代码topthink/framework以及各种功能扩展。很多新手会困惑为什么官网下载的压缩包里没有vendor因为官方源码包默认不附带依赖需要你自己执行composer install来生成。判断下载有没有成功最直接的标准就是看vendor目录是否存在。后续如果执行composer update这个目录里的内容会跟着更新。这里我有一个建议vendor目录不需要提交到 Git 仓库正确做法是在项目根目录创建.gitignore文件把/vendor写进去让每个开发者克隆代码后自己执行composer install。这样代码库体积小也避免了不同操作系统下依赖二进制文件不一致的问题。4. 官网打包下载与本地运行的完整步骤4.1 官网获取源码包适合快速体验的场景虽然我个人强烈推荐 Composer 方式但确实有一些场景下官网下载更方便比如内网服务器不能访问外网 Composer 源或者你只是想本地快速看下框架代码长什么样。官网提供的源码包是一个压缩文件解开后就能看到完整的框架目录。不过在动手之前你要有个心理准备这种源码包同样不包含vendor依赖下载完后它只能看不能跑。如果你在内网环境只能靠源码包离线部署过程会比 Composer 方式繁琐一些。我一般会在有外网的机器上用create-project把完整项目装好然后用tar或zip压缩整个目录再传到内网机器解压。这样vendor目录被打包进去内网机器不需要装 Composer 也能运行这是我在某实验室部署时验证过的可靠方案。4.2 放到 Web 服务器入口文件与伪静态配置源码包解压后你会看到public目录这是框架唯一的对外入口。我之前见过有人把项目整个放到站点根目录访问时直接跳到了目录列表或者首页能打开但其他页面全部 404。原因就是没有把站点根目录指向public也没有配伪静态。以 Nginx 为例站点配置的root要指向项目的public目录server { listen 80; server_name your-domain.com; root /var/www/tp6/public; index index.php index.html; location / { if (!-e $request_filename) { rewrite ^(.*)$ /index.php?s$1 last; } } location ~ \.php($|/) { fastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } }这里的核心是rewrite那行当请求的路径在文件系统里不存在时把请求交给index.php处理框架再根据s参数解析路由。如果你用的是 Apache对应的伪静态规则是IfModule mod_rewrite.c Options FollowSymlinks -Multiviews RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*)$ index.php?s/$1 [QSA,PT,L] /IfModule这段规则要放到public/.htaccess文件里。很多人在本地用 PHP 内置服务器开发完全不需要这些伪静态配置但一上服务器就各种 404基本都是漏了这一步。4.3 首次运行开启调试模式看真实错误配置完成后浏览器访问你的域名如果能看到 ThinkPHP 的默认欢迎页面说明框架已经跑起来了。如果页面是空白或者 500 错误那多半是 PHP 报错了但被隐藏了。TP6 默认是关闭调试模式的错误信息不会直接显示在页面上而是写进日志文件。我刚入门时不懂这个白屏就不知道怎么办后来才会去查日志。开启调试模式的方法是修改项目根目录下的.env文件APP_DEBUGtrue APP_TRACEtrue.env文件在create-project生成的项目里是存在的但如果你用的是官网源码包可能没有这个文件需要手动复制.example.env为.env。开启后刷新页面浏览器会直接显示异常详细信息包括错误文件、行号和调用链。排错完成后别忘了把APP_DEBUG改回false毕竟生产环境暴露错误堆栈是很危险的事情。我的习惯是本地开发永远开着调试模式部署到测试环境关一半到生产环境必须全关。5. ThinkPHP 6 下载后的 5 个常见坑与排查5.1 坑一composer install报错说 PHP 版本不满足现象在本地执行composer install时提示类似Your PHP version (7.1.3) does not satisfy that requirement。原因Composer 读取的是命令行 PHP 版本而不是浏览器访问的那个。有时候你安装了多个 PHP 版本命令行默认指向了旧版本。解决where phpWindows或which phpLinux确认实际调用的 PHP 路径。如果指向了旧版本要么修改环境变量要么在 Composer 命令前手动指定比如/usr/bin/php8.1 composer install。改完以后再执行php -v确认版本已经切换这个操作需要在新开的终端窗口里才会生效。5.2 坑二项目下载好了但访问首页出现一堆警告现象首页能打开但页面顶部出现黄色的Deprecated警告或者Warning级别的错误。原因PHP 版本高于框架预期某些旧的写法在更高的 PHP 版本里被标记为弃用。这个在 PHP 8.0 以上跑 TP6.0 时比较常见。解决在.env文件里设置APP_DEBUGfalse生产环境本来就不该显示警告。如果还想看到警告信息做兼容性调整可以在public/index.php入口文件顶部临时加入error_reporting(E_ALL ~E_DEPRECATED);来屏蔽弃用类报错。但这不是长久之计最好还是升级框架到 6.1 系列或者针对报错提示的代码做兼容修改。5.3 坑三伪静态配了但模块访问还是 404现象首页访问正常但访问/index/user/list这种多级路径返回 404或者直接找不到页面。原因TP6 的路由模式和伪静态规则不匹配。TP6 默认使用混合路由模式路径里的index是应用名user是控制器list是方法。伪静态规则只重写了一次没有正确传递完整的路径参数。解决先确认访问index.php?s/index/user/list是否能正常访问如果能说明确实是伪静态问题。检查 Nginx 配置里的 rewrite 规则是否把$request_filename判断写对了文件路径不存在的条件漏了就会跳过重写。还有一种是 Nginx 配置里有多个location段互相干扰我建议把location /里的 rewrite 配置移到server层级试试避开 location 匹配的优先级问题。5.4 坑四连接数据库报could not find driver现象安装没问题但一操作数据库就报PDOException: could not find driver。原因PHP 装了 PDO 扩展但没装具体的数据库驱动。比如连 MySQL 需要pdo_mysql扩展只装pdo是不够的。解决执行php -m | grep pdo查看已装的 PDO 相关扩展。如果没有pdo_mysql在 Windows 上去掉php.ini里extensionpdo_mysql前的分号注释然后重启服务在 Ubuntu 上执行sudo apt install php-mysql在 CentOS 上执行sudo yum install php-mysqlnd。装完后再次确认扩展加载成功是跑数据库的前提。5.5 坑五静态文件全部 404样式和图片都不显示现象页面 HTML 能正常输出但 CSS、JS、图片全部访问不了浏览器控制台一片红。原因项目配置了强制 HTTPS 或者域名根路径不对静态资源路径用的是绝对路径但在当前环境下解析不到。还有一种情况是安装的时候用的是站点根目录而不是public目录导致静态资源路径全部错位。解决如果用的 Nginx 站点配置检查root是否指向了public目录确保location ~ \.php里SCRIPT_FILENAME也能正确拼接出文件路径。另外在 TP6 的模板视图里优先使用url()工具函数生成资源路径别手写相对路径。手写路径一旦调整目录层级就会翻车这是我见过的最容易出现的问题没有之一。6. 最后一步让下载完的框架跑出第一个页面的两个验证技巧6.1 用内置命令快速启动开发服务器框架跑通以后你不需要每次都配置 Nginx 或 Apache 来做开发调试。TP6 自带了 PHP 内置服务器启动命令php think run默认监听8000端口浏览器访问http://localhost:8000。如果想改端口和绑定地址php think run -H 0.0.0.0 -p 8080-H指定监听地址0.0.0.0表示允许外部机器访问-p指定端口。这个命令特别适合本地写接口联调的时候不用开完整的 Web 服务器启动快日志输出也直观。我在某公司做过一个模拟项目X的接口服务全流程就是靠php think run做单测联调的。6.2 用日志验证框架核心链路完整如果默认欢迎页出不来除了开调试模式还可以直接看运行时日志。TP6 的日志默认写在runtime/log/目录按日期生成文件。查看某个时间段的日志tail -f runtime/log/202501.log日志会记录包括路由解析、SQL 执行、异常堆栈在内的所有关键信息。有一次我在帮某跨平台系统排查问题时页面白屏但日志里什么都有最后发现是模板缓存目录没有写权限。runtime目录在 Linux 下必须给 Web 用户写权限chmod -R 775 runtime chown -R www-data:www-data runtime这个权限问题是黑匣子级别的坑PHP 不报错但功能就是不对。我的习惯是每次新环境部署完强制看一眼日志目录有没有写入内容没有内容说明权限或路径有问题早发现早处理。希望这个排查习惯能帮到你祝少踩坑。本文还有配套的精品资源点击获取