在WordPress WooCommerce站点集成three.js落地页引发AJAX购物车异常

问题 #

我有一个标准WordPress WooCommerce站点，最近把带WooCommerce跳转链接的three.js落地页集成到站点里，把相关.js文件和index.html上传到public_html目录来展示动画落地页。但操作后，AJAX「加入购物车」功能和侧边迷你购物车失效，其他功能正常。哪怕用完全空白的index.html文件，这个问题还是会出现。我试过把three.js部署到测试站再跳转到主站，这个方案功能正常但满足不了同域名需求。想问：

1. 添加index.html为什么会干扰WooCommerce的AJAX功能？
2. 有没有不需要index.html的three.js落地页集成方案？

附上传的index.html内容：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="/assets/EveryRep-logo-black-DcJJJvSs.svg" type="image/svg+xml">
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>EveryRep - Premium Sustainable Athletic Apparel for Fitness Enthusiasts</title>
    <meta name="description" content="EveryRep - Premium Sustainable Athletic Apparel for Fitness Enthusiasts" />
    <meta name="keywords" content="fitness, athletic apparel, sustainable clothing, ecofriendly, workout clothes, gym wear, yoga pants, running shoes, mens clothing, womens clothing, activewear, outdoor gear, hiking boots">
    <meta name="author" content="EveryRep">
    <meta name="robots" content="index,follow">
    <meta name="google-site-verification" content="Google verification token">
    <meta property="og:title" content="EveryRep - Premium Sustainable Athletic Apparel for Fitness Enthusiasts">
    <meta property="og:description" content="EveryRep - Premium Sustainable Athletic Apparel for Fitness Enthusiasts">
    <meta property="og:image" content="/src/assets/EveryRep-logo-black.svg">
    <meta property="og:url" content="https://everyrep.com">
    <meta property="og:type" content="website">
    <script type="module" crossorigin src="/assets/index-DsGnWYTW.js"></script>
    <link rel="stylesheet" crossorigin href="/assets/index-BxLv6ccw.css">
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

原因分析 #

1. 服务器优先级冲突 #

Web服务器（比如Apache/Nginx）默认会优先加载根目录下的index.html，而不是WordPress的核心入口index.php。这直接跳过了WordPress的全局初始化流程——包括WooCommerce AJAX依赖的wp-admin/admin-ajax.php路由、用户会话Cookie、全局JS变量（比如wc_add_to_cart_params）都没被正确加载。哪怕是空白的index.html，只要它在根目录，服务器就会返回它，替代WordPress的页面渲染，AJAX请求失去后端上下文，自然失效。

2. 会话与验证信息丢失 #

WooCommerce的AJAX加购和迷你购物车功能依赖WordPress的用户会话、wpnonce验证机制，以及全局配置变量。当服务器返回index.html时，这些关键信息根本没被注入到页面里，AJAX请求要么找不到正确的后端接口，要么验证失败，最终导致功能罢工。

解决方案 #

方案1：调整服务器优先级，让WordPress优先加载 #

Apache服务器

在根目录的.htaccess文件里修改DirectoryIndex顺序，把index.php放在最前面：

DirectoryIndex index.php index.html index.htm

这样服务器会先加载WordPress的入口，你的three.js落地页可以放在子目录（比如/landing/），或者通过WordPress页面模板嵌入。

Nginx服务器

在站点配置的location /块中调整index指令顺序：

location / {
    index index.php index.html index.htm;
    try_files $uri $uri/ /index.php?$args;
}

方案2：无需index.html的three.js集成方案 #

方法A：制作WordPress页面模板嵌入

1. 在你的WordPress主题目录下新建page-threejs-landing.php文件，内容如下：

<?php
/*
Template Name: Three.js Landing Page
*/
get_header();
?>
<div id="root"></div>
<script type="module" crossorigin src="<?php echo get_template_directory_uri(); ?>/assets/index-DsGnWYTW.js"></script>
<link rel="stylesheet" crossorigin href="<?php echo get_template_directory_uri(); ?>/assets/index-BxLv6ccw.css">
<?php
get_footer();
?>

2. 把three.js的assets目录放到主题目录下。
3. 在WordPress后台新建页面，选择「Three.js Landing Page」模板，发布后设置该页面为首页（设置→阅读→首页显示→静态页面）。

方法B：用短代码嵌入three.js动画

1. 在主题的functions.php里添加短代码函数：

function threejs_landing_shortcode() {
    ob_start();
    ?>
    <div id="root"></div>
    <script type="module" crossorigin src="<?php echo get_template_directory_uri(); ?>/assets/index-DsGnWYTW.js"></script>
    <link rel="stylesheet" crossorigin href="<?php echo get_template_directory_uri(); ?>/assets/index-BxLv6ccw.css">
    <?php
    return ob_get_clean();
}
add_shortcode('threejs_landing', 'threejs_landing_shortcode');

2. 把three.js资源放到主题目录，然后在需要展示的页面/文章里插入[threejs_landing]短代码就行。

方法C：自定义插件集成（不修改主题）

1. 在wp-content/plugins/目录下新建threejs-landing文件夹，里面创建threejs-landing.php：

<?php
/*
Plugin Name: Three.js Landing Page
Description: 集成three.js落地页到WordPress
Version: 1.0
Author: Your Name
*/

function threejs_landing_enqueue_assets() {
    if (is_front_page()) { // 仅在首页加载资源
        wp_enqueue_style('threejs-landing-css', plugin_dir_url(__FILE__) . 'assets/index-BxLv6ccw.css');
        wp_enqueue_script('threejs-landing-js', plugin_dir_url(__FILE__) . 'assets/index-DsGnWYTW.js', array(), false, true);
    }
}
add_action('wp_enqueue_scripts', 'threejs_landing_enqueue_assets');

function threejs_landing_render_content() {
    if (is_front_page()) {
        echo '<div id="root"></div>';
    }
}
add_action('wp_body_open', 'threejs_landing_render_content');

2. 把three.js的assets目录放到插件文件夹里，后台激活插件后，设置首页为静态页面即可。

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