正文

Craft CMS实战，从本地环境到生产部署，一个老司机的完整拆解和血泪教训

小海不是菜
小海不是菜 V管理员 /891阅读/3评论
0718
文章最后更新时间2026年07月18日，若文章内容或图片失效，请留言反馈！

适用人群

这篇文章写给谁？不是给那些只想点几下鼠标就“建站”的老板，也不是给连命令行都没见过的“拖拽党”，你是前端开发者？还是刚入门的PHP爱好者？或者你厌倦了WordPress那臃肿的插件和慢吞吞的更新，想找个干净、灵活、连前端都能完全自己掌控的CMS？只要你会一点点命令行（cd、ls、composer），知道“服务器”不是个黑盒子，那咱们就能聊，Craft CMS适合那些愿意花半小时读文档、换回未来几年“想改什么就改什么”自由的人，不适合急性子——别指望5分钟出站，但一旦搭好，你就再也不想碰那些“开箱即用”的垃圾了。

完整搭建步骤（本地环境为例）

第一步：准备好你的工具箱

别用那些乱糟糟的集成环境（XAMPP？省省吧），我推荐直接上Docker或者用Homestead，但考虑到大多数人只是本地跑一下，咱们用最干净的PHP内置服务器+SQLite（没错，Craft支持SQLite，新手友好），不过如果你打算上线，还是用MySQL/PostgreSQL，我这里以MySQL为例。

Craft CMS实战，从本地环境到生产部署，一个老司机的完整拆解和血泪教训

Craft CMS实战，从本地环境到生产部署，一个老司机的完整拆解和血泪教训

必须有的东西：

  • PHP 8.1+（推荐8.2或8.3）
  • Composer（没装？去getcomposer.org，三分钟搞定）
  • MySQL 8.0+ 或 MariaDB 10.4+
  • Node.js（别问为什么，因为Craft用了Webpack处理前端，虽然你可以跳过，但会有个坑，后面说）

第二步：创建项目，别手贱改文件

打开终端,进到你放网站的目录，~/Sites/，跑一行：

composer create-project craftcms/craft my-craft-site

等啊等,看见 vendor 目录出现别激动——这是Composer在下载依赖，如果卡在某个包，八成是网络问题，换国内镜像（阿里云或腾讯云）：

composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/

再跑一次,创建完成后，你会得到一个干净的目录结构，别急着改任何文件，特别是 .env 和 config/ 下的东西，除非你知道自己在干嘛。

第三步：配置数据库和.env

进入项目根目录,复制 .env.example 为 .env，用你喜欢的编辑器打开 .env，改这几行：

DB_DRIVER=mysql
DB_SERVER=127.0.0.1
DB_PORT=3306
DB_DATABASE=craft_db   # 提前在MySQL里创建一个空数据库，名字随意
DB_USER=root
DB_PASSWORD=你的密码
DB_SCHEMA=public

别用root上线！ 本地开发无所谓，但养成好习惯：新建一个数据库用户，只给这个库的权限。

第四步：跑安装程序

在项目目录下,执行：

php craft install

它会问你站点名称、管理员邮箱、密码等，一步步回答，注意：密码要够复杂（至少大写+数字+符号），不然Craft会报错，如果你怕麻烦，可以在 .env 里预定义：

SECURITY_KEY=随便写个32位随机字符串

但最好还是让它自动生成。

等几秒钟,你会看到 “Craft CMS is now installed.” 然后打开浏览器输入 http://localhost:8000？等等，还没启动服务呢，在项目目录运行：

php craft serve

默认端口是8000,打开浏览器访问 http://localhost:8000，你应该看到Craft的欢迎页面，然后进入控制面板（/admin），恭喜，你已经成功了一半，剩下的一半在下面。

第五步：配置前端构建（这一步很多人翻车）

Craft默认使用Vite进行前端资源构建（较新版），控制面板好看，但前端页面是空的？因为 templates/ 目录下只有默认的 index.twig，你需要先运行：

npm install
npm run build

如果提示没有 package.json，检查是否用了 craftcms/craft 这个骨架，它自带 package.json，如果还是没有，手动在根目录创建一个空的，npm init -y，再安装依赖：

npm install --save-dev vite @craftcms/vite

然后按照文档配置 vite.config.js，但这里有个常见坑：如果你只是本地使用，可以用 php craft serve 直接跑，不需要Vite也能看到页面，但如果你用了Twig模板中的 {% script %} 或 {% css %} 标签，必须构建，新手建议：先屏蔽前端构建，直接在 templates/ 里写纯HTML+CSS，用Craft的模板引擎输出内容，这样零门槛。

配置要点（老司机的私房菜）

  1. 环境文件 .env 里的 APP_URL 务必写对，本地写 http://localhost:8000，线上写实际域名，结尾不要斜杠，错了会导致资源路径乱掉。

  2. Craft的“Matrix”字段是你的武器，别用“内容编辑器”的思维去理解Craft——它没憋着给你一堆默认字段，你需要先建好“Entry Types”（入口类型），给每个页面定义字段组，文章”要有标题、正文、封面图、标签，用Matrix字段（类似Ace的组件）可以实现高度复用的内容模块，英雄图+标题+按钮”可重复添加。千万别把所有内容塞进一个大富文本字段，否则Craft的灵活优势全丢了。

  3. 模板缓存，Craft默认开启模板缓存（devMode 为false时），你在改模板后看不到变化？去控制面板 > 设置 > 缓存里清一下，或者本地开发时将 .env 的 DEV_MODE 设为 true，ENABLE_TEMPLATE_CACHING 设为 false。

  4. URL规则，Craft的URL完全自由，你可以让 news/2024/tech 指向某个Entry，也可以让 products/my-product-name 指向另一个，在 config/routes.php 里自定义，新手可以先忽略，用控制面板的“条目”自动路由。

  5. 用户权限别偷懒，Craft的用户组系统极细，上线后给内容编辑员只给“编辑条目”的权限，别给“系统设置”，否则某天你发现IP被改了，哭都来不及。

常见踩坑提醒（我替你试过毒了）

坑1：安装时卡在“Creating tables…”
八成是MySQL字符集问题，Craft要求 utf8mb4，但你创建的数据库可能是 latin1，解决方法：建库时指定：

CREATE DATABASE craft_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

坑2：Composer安装超时
国内直连容易断，除了换镜像，还可以加 --no-interaction 参数跳过交互确认，另外确认PHP内存限制够大，php -i | grep memory_limit 至少要256M，推荐512M。

坑3：控制面板白屏或500错误
检查 storage/logs/ 下的 web.log 或 php-error.log，最常见原因是 .env 里 SECURITY_KEY 为空或不合法——删除 .env 里的 SECURITY_KEY 行，重新 php craft install 让它生成。

坑4：图片上传失败
Craft依赖 gd 或 imagick 扩展，检查 php -m | grep gd，没有就装上，另外上传文件大小受PHP限制，改 php.ini 的 upload_max_filesize 和 post_max_size 为20M以上。

坑5：本地站点能访问，但线上部署后css/js全部404
这是路劲问题，线上需要更新 .env 里的 APP_URL 为实际域名，并且确保 web/ 目录是服务器根目录（重要！不要把整个项目目录设为根目录，否则安全风险巨大），另外检查 web/cpresources/ 目录是否可写——Craft会把一些资源符号链接或复制到这里。

坑6：升级时胆战心惊
Craft升级很频繁，但千万别直接覆盖文件，用Composer：

composer update craftcms/plugin-oembed --with-all-dependencies

然后记得跑 php craft migrate/all，升级前备份数据库和 storage/ 目录，这是铁律。