加载自定义APISIX插件时resty.core模块加载失败求助

问题描述 #

在APISIX 2.15.0 Docker环境开发自定义Lua插件，参考官方示例及开发指南配置加载后，重载APISIX时出现模块加载错误，插件无法正常加载。

错误信息 #

2022/10/05 14:05:40 [alert] 1#1: failed to load the 'resty.core' module (https://github.com/openresty/lua-resty-core); ensure you are using an OpenResty release from https://openresty.org/en/download.html (reason: /usr/local/apisix/apisix/plugins/3rd-party.lua:18: loop or previous error loading module 'apisix.core') in /usr/local/apisix/conf/nginx.conf:404

复现步骤 #

• 克隆带有Docker Compose栈的APISIX Docker仓库示例项目
• 创建目录<repo>/example/plugins
• 在该目录下创建3rd-party.lua并写入指定Lua代码
• 编辑<repo>/apisix_conf/config.yaml，在apisix节点下添加extra_lua_path: "/usr/local/apisix/apisix/plugins/3rd-party.lua"
• 在docker-compose的apisix服务volumes部分添加- ./plugins/3rd-party.lua:/usr/local/apisix/apisix/plugins/3rd-party.lua挂载脚本
• 执行cd ./example && docker-compose up -d启动服务
• 检查插件加载状态

插件代码 #

local require       = require
local core          = require("apisix.core")
local plugin_name   = "3rd-party"


local schema = {
    type = "object",
    properties = {
        body = {
            description = "body to replace response.",
            type = "string"
        },
    },
    required = {"body"},
}

local plugin_name = "3rd-party"

local _M = {
    version = 0.1,
    priority = 12,
    name = plugin_name,
    schema = schema,
}


function _M.check_schema(conf)
    return core.schema.check(schema, conf)
end


function _M.access(conf, ctx)
    return 200, conf.body
end


return _M

问题分析 #

1. 核心错误原因：extra_lua_path配置错误，直接指向了单个插件文件而非插件目录。APISIX加载插件时需要扫描指定目录下的所有Lua模块，单个文件的路径配置会干扰模块加载逻辑，导致apisix.core模块加载时出现循环引用错误。
2. 次要冗余问题：插件代码中重复定义了plugin_name变量，虽不直接导致加载失败，但属于冗余代码。

解决方案 #

1. 修正extra_lua_path配置 #

编辑<repo>/apisix_conf/config.yaml，将原配置修改为指向插件目录的通配符路径：

apisix:
  # 其他配置...
  extra_lua_path: "/usr/local/apisix/apisix/plugins/?.lua"

2. 调整Docker挂载方式 #

修改docker-compose.yml中apisix服务的volumes配置，挂载整个plugins目录而非单个文件：

services:
  apisix:
    # 其他配置...
    volumes:
      # 其他挂载项...
      - ./plugins/:/usr/local/apisix/apisix/plugins/

3. 清理冗余代码（可选） #

删除插件代码中重复的local plugin_name = "3rd-party"定义，保留顶部的一次定义即可。

4. 重启服务并验证 #

执行以下命令重启APISIX服务：

cd ./example && docker-compose restart apisix

通过Admin API验证插件是否加载成功：

curl http://localhost:9080/apisix/admin/plugins/list -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1"

返回结果中若包含"3rd-party"，则说明插件加载成功。

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