Docker部署Directus 11.1.1后新增POST API扩展失败求助

一、检查扩展基础结构是否合规 #

Directus的端点（Endpoint）扩展有严格的结构要求，以下是核心配置要点：

1. package.json 配置 #

确保directus:extension字段的类型为endpoint，且host版本匹配11.x：

{
  "name": "directus-extension-custom-post",
  "version": "1.0.0",
  "type": "module",
  "directus:extension": {
    "type": "endpoint",
    "path": "dist/index.js",
    "source": "src/index.js",
    "host": "^11.0.0"
  },
  "scripts": {
    "build": "directus-extension build"
  },
  "dependencies": {
    "@directus/extensions-sdk": "11.1.1"
  }
}

2. 入口文件（src/index.js）结构 #

必须导出包含routes数组的对象，POST方法配置要明确：

export default {
  routes: [
    {
      method: 'POST',
      path: '/custom-post-endpoint', // 自定义唯一路径，避免和内置路由冲突
      handler: async (req, res) => {
        // 示例POST逻辑：接收并返回请求体
        try {
          const requestData = req.body;
          // 这里可以添加业务逻辑，比如操作数据库、调用外部API等
          res.status(200).json({
            success: true,
            received: requestData
          });
        } catch (error) {
          res.status(500).json({
            success: false,
            error: error.message
          });
        }
      },
      auth: false, // 先设为false测试，确认可用后再开启权限验证
      // auth: true // 开启后需确保用户有对应权限
    }
  ]
};

二、构建与Docker部署验证 #

1. 本地构建扩展 #

在扩展目录执行：

npm install
npm run build

确认生成dist/index.js文件，这是Directus实际加载的文件。

2. Docker挂载路径检查 #

如果是本地挂载扩展，确保挂载到Directus的端点扩展目录：

docker run -v ./path/to/your/extension:/directus/extensions/endpoints/custom-post-endpoint directus/directus:11.1.1

注意：必须放在endpoints目录下，而非其他类型扩展目录（如interfaces、modules）。

如果是通过Dockerfile集成扩展，确保构建步骤正确：

FROM directus/directus:11.1.1

# 复制并构建扩展
WORKDIR /directus/extensions/endpoints/custom-post-endpoint
COPY package*.json ./
RUN npm install --production
COPY src/ ./src/
RUN npm run build

# 启动Directus
CMD ["npx", "directus", "start"]

三、排查加载与权限问题 #

1. 查看Directus日志 #

通过Docker日志定位错误：

docker logs <your-directus-container-id>

常见错误包括：

• 语法错误：检查src/index.js的代码是否符合ES模块规范
• 依赖缺失：确认扩展的依赖已正确安装
• 路径冲突：检查自定义路由是否与Directus内置路由重复

2. 权限验证 #

先将auth: false测试端点是否可访问（用Postman或curl发送POST请求到http://your-directus-url/custom-post-endpoint）。如果能正常响应，再开启auth: true并配置对应权限：

• 在Directus后台创建自定义权限，关联该端点
• 确保测试用户拥有该权限

四、常见错误排查 #

• 扩展类型错误：误将endpoint写成其他类型（如operation）
• 未构建扩展：直接挂载src目录，Directus无法识别未编译的代码
• 路由路径冲突：使用了Directus内置路径（如/items、/auth）
• Node版本不兼容：确保扩展构建时的Node版本与Directus容器内的Node版本一致（Directus 11.x通常使用Node 18+）

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