Shopify应用安装与加载时NextJS抛出'pages is undefined'错误排查求助

这个错误看起来是NextJS路由解析时的pages数组未初始化导致的，结合你的路由结构和错误上下文，我整理了几个针对性的解决方案：

1. 修复重复的路由目录（最可能的核心原因） #

看你的路由结构，/pages下存在两个同名的/customers目录：

• 一个包含index.tsx和[customerId].tsx
• 另一个包含data_request.tsx和redact.tsx

NextJS Pages Router不允许在根pages目录下出现同名的嵌套目录，这会打乱它自动生成路由列表（也就是pages变量）的逻辑，直接导致路由解析时出现pages is undefined的错误。

修复方案：
把存放GDPR Webhook的/customers目录移到/api下（因为Webhook属于后端接口），调整后的路由结构应该是：

• /pages
  • _app.tsx
  • index.tsx
  • /customers
    • index.tsx
    • [customerId].tsx
  • /api
    • auth.tsx
    • graphql.tsx
    • /customers
      • data_request.tsx
      • redact.tsx
  • /auth
    • callback.tsx
  • /shop
    • redact.tsx

2. 优化_app.tsx的初始化顺序 #

Shopify应用是嵌入在Shopify后台iframe中的，路由解析可能会在App Bridge完全初始化前触发，导致NextJS的路由系统还没准备好完整的pages列表。

可以在_app.tsx中添加条件渲染，确保App Bridge和路由相关资源加载完成后再渲染页面：

import { AppProps } from 'next/app';
import { useEffect, useState } from 'react';
import AppBridge from '@shopify/app-bridge';
import { Provider } from '@shopify/app-bridge-react';

function MyApp({ Component, pageProps }: AppProps) {
  const [appReady, setAppReady] = useState(false);

  useEffect(() => {
    // 初始化Shopify App Bridge
    const app = AppBridge.create({
      apiKey: process.env.NEXT_PUBLIC_SHOPIFY_API_KEY!,
      shopOrigin: pageProps.shopOrigin,
    });

    // 标记应用就绪，确保路由解析时pages已生成
    setAppReady(true);
  }, [pageProps.shopOrigin]);

  // 未就绪时显示加载状态，避免提前触发路由解析
  if (!appReady) {
    return <div>Loading...</div>;
  }

  return (
    <Provider app={app}>
      <Component {...pageProps} />
    </Provider>
  );
}

export default MyApp;

3. 检查NextJS版本兼容性 #

部分旧版本的NextJS在和Shopify App Bridge配合时，会存在路由初始化的时序问题。建议升级到最新的稳定版Pages Router版本（比如13.5.x系列），或者回退到已知兼容的版本（比如12.3.x），避免版本bug导致的pages变量未定义。

4. 排查next.config.js的自定义路由配置 #

如果你的next.config.js中有rewrites、redirects或trailingSlash等配置，确保它们没有和动态路由冲突。比如开启trailingSlash: true可能会影响路由解析逻辑，建议暂时关闭测试，或者调整规则匹配顺序。

先试试第一个方案（修复重复路由目录），这是最可能解决问题的点，如果不行再依次尝试其他方案。

内容的提问来源于stack exchange，提问作者Paul van den Dool