迁移React+CRA应用至Squarespace的脚本加载依赖问题求助

核心思路 #

利用CRA构建后自动生成的asset-manifest.json动态获取哈希资源路径，同时通过串行加载严格控制jQuery、Popper、Bootstrap的依赖顺序，彻底解决文件名变更和加载时序错误的问题，全程无需eject CRA或手动更新Squarespace代码。

具体实现步骤 #

1. 动态读取CRA资源清单 #

CRA每次构建都会在build目录生成asset-manifest.json，里面包含所有哈希后的CSS/JS资源路径。我们通过这个文件自动获取最新资源，不用再手动写死文件名。

2. 串行加载资源保证依赖顺序 #

并行加载脚本会导致依赖顺序混乱，所以用Promise+async/await实现串行加载，确保：

• CSS先加载
• jQuery → Popper → Bootstrap 依次加载
• React相关JS按runtime→vendors→main的顺序加载

3. 修正Tooltip初始化时机 #

在React组件中，确保jQuery和Bootstrap完全加载后再初始化Tooltip，避免过早调用导致的错误。

完整代码示例 #

Squarespace代码块中的加载脚本 #

// 替换成你的GitHub Pages应用根地址
const APP_BASE_URL = 'https://your-username.github.io/your-react-app/';

// 串行加载资源的工具函数
function loadResource(url, type = 'script') {
  return new Promise((resolve, reject) => {
    const element = type === 'script' 
      ? document.createElement('script') 
      : document.createElement('link');
    
    if (type === 'script') {
      element.src = url;
      element.async = false; // 关闭异步，保证加载顺序
    } else {
      element.rel = 'stylesheet';
      element.href = url;
    }

    element.onload = resolve;
    element.onerror = () => reject(new Error(`Failed to load ${url}`));
    document.head.appendChild(element);
  });
}

// 主加载逻辑
async function embedReactApp() {
  try {
    // 1. 获取资源清单
    const manifestRes = await fetch(`${APP_BASE_URL}asset-manifest.json`);
    const manifest = await manifestRes.json();

    // 2. 加载所有CSS资源
    const cssAssets = Object.values(manifest.files).filter(path => path.endsWith('.css'));
    for (const cssPath of cssAssets) {
      await loadResource(`${APP_BASE_URL}${cssPath}`, 'link');
    }

    // 3. 加载Bootstrap依赖（顺序不能乱）
    // 如果你是通过npm引入的Bootstrap，这部分可能已经包含在CRA的chunk里，可跳过
    await loadResource('https://code.jquery.com/jquery-3.6.4.min.js');
    await loadResource('https://cdn.jsdelivr.net/npm/@popperjs/core@2.11.7/dist/umd/popper.min.js');
    await loadResource('https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.min.js');

    // 4. 按正确顺序加载React应用JS
    const jsAssets = Object.values(manifest.files)
      .filter(path => path.endsWith('.js'))
      .sort((a, b) => {
        // 优先加载runtime，然后是vendors，最后是主代码
        if (a.includes('runtime')) return -1;
        if (b.includes('runtime')) return 1;
        if (a.includes('vendors')) return -1;
        if (b.includes('vendors')) return 1;
        return 0;
      });
    
    for (const jsPath of jsAssets) {
      await loadResource(`${APP_BASE_URL}${jsPath}`);
    }

    // 5. 监听React应用挂载完成后初始化Tooltip
    const rootObserver = new MutationObserver((mutations) => {
      const appRoot = document.getElementById('root');
      if (appRoot && appRoot.children.length > 0) {
        rootObserver.disconnect();
        // 初始化所有Tooltip
        window.$('[data-bs-toggle="tooltip"]').tooltip();
      }
    });
    rootObserver.observe(document.body, { childList: true, subtree: true });

  } catch (err) {
    console.error('加载React应用失败:', err);
  }
}

// 页面DOM加载完成后执行
window.addEventListener('DOMContentLoaded', embedReactApp);

调整Header.js中的Tooltip逻辑 #

import { useEffect, useRef } from 'react';

const Header = () => {
  const tooltipElement = useRef(null);

  useEffect(() => {
    // 确保jQuery和Bootstrap都已加载完成
    if (!window.$ || !window.$.fn.tooltip) return;

    // 初始化Tooltip
    const tooltip = window.$(tooltipElement.current).tooltip();

    // 组件卸载时清理Tooltip
    return () => {
      tooltip.tooltip('dispose');
    };
  }, []);

  return (
    <div 
      ref={tooltipElement}
      data-bs-toggle="tooltip"
      title="你的提示文本"
    >
      {/* Header内容 */}
    </div>
  );
};

export default Header;

Squarespace页面配置 #

1. 在需要嵌入React应用的页面添加一个代码块，选择HTML模式
2. 先插入React根节点：

<div id="root"></div>

3. 再粘贴上面的加载脚本
4. 保存并发布页面

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