如何在Craft CMS 4中创建并安装简单插件？

一、前置准备 #

• 确认本地环境满足Craft 4要求：PHP 8.0+、Composer 2.x、本地服务器（如XAMPP/WAMP）
• 本地已有可正常运行的Craft 4项目

二、用官方脚手架快速初始化插件（推荐） #

手动编写composer.json容易出错，官方脚手架能帮你生成标准结构：

1. 进入Craft项目根目录，执行命令：

   composer create-project craftcms/plugin-starter plugins/YourPluginName
   

   把YourPluginName替换为你的插件名称（比如HelloWorld），插件会生成在项目的plugins/目录下
2. 按提示填写信息：
   • 插件ID：必须是小写+短横线格式（如hello-world）
   • 插件名称：后台显示的名称（如Hello World）
   • 描述、作者信息等按需填写即可

三、手动配置核心文件（若不用脚手架） #

如果坚持手动搭建，重点检查以下文件：

1. 插件根目录composer.json #

确保关键字段正确：

{
    "name": "your-vendor-id/your-plugin-id",
    "type": "craft-plugin",
    "require": {
        "craftcms/cms": "^4.0.0"
    },
    "autoload": {
        "psr-4": {
            "YourNamespace\\YourPluginName\\": "src/"
        }
    }
}

• name：格式为「你的厂商ID/插件ID」，需与后续命名空间对应
• autoload：PSR-4规则要和src/目录下的代码结构完全匹配

2. src/Plugin.php #

确保类继承正确且命名空间一致：

namespace YourNamespace\YourPluginName;

use craft\base\Plugin;

class YourPluginName extends Plugin
{
    public string $schemaVersion = '1.0.0';
    public bool $hasCpSection = false; // 不需要后台页面就设为false
}

四、本地安装插件 #

1. 在Craft项目根目录的composer.json中添加本地插件仓库：

   "repositories": [
       {
           "type": "path",
           "url": "./plugins/YourPluginName"
       }
   ]
   

2. 执行安装命令：

   composer require your-vendor-id/your-plugin-id:dev-main
   

   dev-main是插件默认分支名，若你改过分支需对应调整
3. 登录Craft后台，进入「设置」→「插件」，找到你的插件点击「安装」

五、常见问题排查 #

• 检查PHP版本是否≥8.0，Craft 4不支持更低版本
• 确认插件目录权限正常，服务器可读写
• 执行composer dump-autoload刷新自动加载规则
• 查看Craft日志文件（storage/logs/web.log），里面会显示具体错误信息，针对性修复

内容的提问来源于stack exchange，提问作者Kishan Mistry