TYPO3 11.5：前端JS调用AJAX路由返回404的原因排查

我尝试通过前端JavaScript调用TYPO3的Controller Action，操作步骤如下：

1. 创建NewsletterController及subscribeAction #

namespace Vendor\MyExtension\Controller;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ServerRequestInterface;

class NewsletterController {
  /** @var ResponseFactoryInterface */
  private $responseFactory;

  public function __construct(ResponseFactoryInterface $responseFactory) {
    $this->responseFactory = $responseFactory;
  }

  public function subscribeAction(ServerRequestInterface $request): ResponseInterface {
    $email = htmlspecialchars($request->getQueryParams()['email']) ?? null;

    $data = [
      'email' => $email,
    ];
    $response = $this->responseFactory->createResponse()
      ->withHeader('Content-Type', 'application/json; charset=utf-8');
    $response->getBody()->write(json_encode($data));
    return $response;
}

2. 注册AJAX路由（Configuration/Backend/AjaxRoutes.php） #

<?php

use \Vendow\MyExtension\Controller\Newsletter\NewsletterController;

return [
  'newsletter_subscribe' => [
    'access' => 'public',
    'path' => '/newsletter/subscribe',
    'target' => NewsletterController::class . '::subscribeAction',
  ],
];

该路由已在TYPO3后台配置模块中可见。

3. 前端JS调用代码 #

window.addEventListener(
  "load",
  () => {
    try {
      /**
       * @type HTMLFormElement[]
       */
      const forms = document.querySelectorAll(".newsletter form");

      forms.forEach((form) => {
        form.addEventListener("submit", async (e) => {
          e.preventDefault();
          const abortController = new AbortController();
          window.addEventListener("beforeunload", () =>
            abortController.abort()
          );

          const formData = new FormData(form);
          const formDataObj = {};
          formData.forEach((value, key) => (formDataObj[key] = value));
          const response = await fetch("/newsletter/subscribe", {
            method: "POST",
            body: JSON.stringify(formDataObj),
            signal: abortController.signal,
          });

          const result = response.ok
            ? await response.json()
            : await response.text();

          console.log({ response, result });
        });
      });
    } catch (error) {
      console.log(error);
    }
  },
  { once: true }
);

但调用时始终返回404状态码，请问可能的原因是什么？

可能的原因分析： #

• 命名空间拼写错误：路由文件中使用了\Vendow\MyExtension\Controller\Newsletter\NewsletterController，但实际Controller的命名空间是Vendor\MyExtension\Controller——这里Vendow多了一个字母w，还额外添加了不存在的Newsletter\子目录路径，导致类找不到。
• 路由注册位置错误：Configuration/Backend/AjaxRoutes.php是后台AJAX路由的配置文件，若你是在前台（前端页面）调用接口，需要把路由配置放在Configuration/Frontend/AjaxRoutes.php中，后台路由仅对TYPO3后端生效。
• 请求路径未遵循TYPO3规则：TYPO3前台AJAX请求需要包含路由前缀（比如传统模式的/index.php?eID=，或友好URL模式下的/ajax/），直接硬编码/newsletter/subscribe无法匹配到路由逻辑。正确的做法是通过TypoScript或ViewHelper将TYPO3.settings.ajaxUrls注入到前端，再从中获取对应路由的完整请求路径。
• 参数获取方式与请求不匹配：前端用POST发送JSON数据，但Controller中用$request->getQueryParams()获取参数——这个方法只能读取URL中的GET参数，POST的JSON数据需要用json_decode($request->getBody()->getContents(), true)解析。
• 缓存未更新：修改路由配置后未清理TYPO3的系统缓存，导致新路由规则未生效。

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