enonic-nextxp-integration

Next.js + Enonic XP 无头集成（Next.XP）

操作步骤

步骤 1：识别工作区集成范围

1. 检查工作区中的 Next.js 入口点（next.config.*、包含 next 依赖的 package.json）、Enonic XP 应用标记（包含 com.enonic.xp 的 build.gradle）或现有的 Next.XP 适配器引用（@enonic/nextjs-adapter）。
2. 在 Node 运行时可用时，执行 node scripts/find-nextxp-targets.mjs .，盘点 Next.js 项目、包含 ENONIC_* 变量的 .env 文件、组件映射文件（_mappings.ts）和 Guillotine 查询文件。
3. 如果 Node 运行时不可用，请手动检查 package.json、.env 和 src/components/_mappings.ts，以识别集成范围。
4. 如果工作区同时包含 Enonic XP 应用和 Next.js 前端，请在继续之前确认任务针对哪一方。
5. 如果工作区不是 Next.js + Enonic XP 项目，请停止并说明此技能不适用。

步骤 2：配置 Enonic 适配器

1. 在编写或修改配置之前，阅读 references/nextxp-reference.md。
2. 在 Next.js 项目根目录中验证或创建 .env 文件（本地开发时使用 .env.local），并设置所需变量：
   • ENONIC_API_TOKEN — 用于预览模式身份验证的共享密钥。
   • ENONIC_APP_NAME — 完整限定的 Enonic 应用名称（例如，com.example.myproject）。
   • ENONIC_MAPPINGS — 区域设置到项目／站点的映射（例如，en:intro/hmdb）。
   • ENONIC_API — Guillotine API 端点的基础 URL（例如，http://127.0.0.1:8080/site/）。
3. 如果尚未安装，请安装 @enonic/nextjs-adapter 包：npm install @enonic/nextjs-adapter。
4. 在 src/components/_mappings.ts 顶部导入 @enonic/nextjs-adapter/baseMappings，以注册内置组件渲染器。
5. 验证 Next.js 项目是否由 nextxp-template 脚手架创建，或是否包含预期的文件结构：src/components/_mappings.ts、src/app/[locale]/[[...contentPath]]/page.tsx，以及 src/app/api/ 下的 API 路由。
6. 阅读 references/compatibility.md，确认 @enonic/nextjs-adapter（v4.x）、Next.js（16+）、React（19）和 Enonic XP 之间的版本要求。 步骤 3：将内容类型映射到 React 组件
7. 阅读 references/nextxp-reference.md，了解组件注册表 API 和映射模式。
8. 阅读 references/examples.md，查看完整的内容类型映射示例，包括查询、视图和处理器。
9. 对于需要自定义渲染的每种 Enonic 内容类型： a. 在 src/components/queries/ 中创建 Guillotine GraphQL 查询函数，使用类型内省（... on AppName_ContentTypeName）获取该内容类型的特定字段。 b. 对于含有 HTML 区域（富文本）字段的内容类型，使用 @enonic/nextjs-adapter 中的 richTextQuery(fieldName) 生成查询片段。富文本渲染部分请参阅 references/nextxp-reference.md。 c. 在 src/components/views/ 中创建 React 视图组件，接收 FetchContentResult 属性并渲染获取的数据。对于 HTML 区域字段，使用 @enonic/nextjs-adapter/views/RichTextView 中的 RichTextView。 d. 在 src/components/_mappings.ts 中使用 ComponentRegistry.addContentType() 注册两者。
10. 对于页面组件（页面、部件、布局）： a. 在 Enonic 应用的 src/main/resources/site/pages/、parts/ 或 layouts/ 下定义组件 XML。 b. 在 src/components/pages/、parts/ 或 layouts/ 中创建对应的 React 组件。布局使用 LayoutProps，单独渲染区域时使用具名导出 RegionView。 c. 使用 ComponentRegistry.addPage()、ComponentRegistry.addPart() 或 ComponentRegistry.addLayout() 注册。
11. 对于布局，使用 LayoutProps 类型，并使用 RegionView（单数形式，具名导出）单独渲染区域，而不是使用 RegionsView。
12. 从 @enonic/nextjs-adapter 导入 APP_NAME 和 APP_NAME_UNDERSCORED，以便动态引用内容类型。

步骤 4：配置 Guillotine 数据获取

1. 阅读 references/nextxp-reference.md，了解 Guillotine 查询结构和变量传递方式。
2. 编写 GraphQL 查询，通过 guillotine { get(key:$path) { ... } } 使用 $path:ID! 作为获取内容的主变量。
3. 使用类型内省访问特定内容类型的字段：... on AppName_ContentTypeName { data { ... } }。
4. 对于富文本字段（HtmlArea），使用适配器中的 richTextQuery(fieldName)，而不是直接查询该字段。使用 @enonic/nextjs-adapter/views/RichTextView 中的 RichTextView 进行渲染。
5. 对于部件和可配置组件，导出一个查询对象，其中包含 query(path, context, config) 和 variables(path, context, config) 函数。
6. 使用处理器（可选的异步函数）对查询结果进行后处理，然后再传递给视图。
7. 使用 ComponentRegistry.setCommonQuery() 设置所有页面组件共享的数据。如果不需要通用查询，请将其移除以优化性能。
8. 使用适配器中的 getUrl() 和 getAsset() 辅助函数处理 URL，确保它们在独立模式和 Content Studio 预览模式下均可正常工作。
9. 对于富文本中的宏，在使用 RichTextView 的其他组件之前，先使用 ComponentRegistry.addMacro() 注册这些宏。宏注册 API 请参阅 references/nextxp-reference.md。 步骤 5：启用 Content Studio 预览模式
10. 阅读 references/nextxp-reference.md，了解完整的预览架构详情。
11. 在 Enonic XP 中安装 Next.XP 应用：XP Menu → Applications → Install → search "Next.XP"。
12. 在 Content Studio 的站点编辑视图中，通过 “Applications” 下拉框将 Next.XP 应用添加到目标站点。
13. 验证默认预览配置：URL 为 http://127.0.0.1:3000，密钥与 ENONIC_API_TOKEN 匹配。
14. 对于生产环境，通过应用配置将 Next.XP 应用配置为使用已部署的 Next.js URL 和共享密钥：

    nextjs.default.url = <Next.js app URL>
    nextjs.default.secret = <shared secret>
    

15. 预览模式会自动将 Guillotine API 切换到 draft 分支，而公开的 Next.js 前端使用 master（已发布）分支。
16. 在所有组件链接中使用 getUrl()，确保 URL 在 Content Studio 的预览、内联和编辑模式下都能正确解析。
17. 如果预览显示空白页面，请阅读 references/troubleshooting.md 了解诊断步骤。

步骤 6：部署到生产环境

1. 阅读 references/nextxp-reference.md，查看部署检查清单。
2. 使用 enonic cloud app install 将 Enonic 应用部署到 Enonic Cloud。
3. 在 Enonic Cloud 中创建 ingress，以公开 Guillotine API（目标路径 /site，公开路径 /api）。
4. 将 Next.js 应用部署到 Vercel 或其他托管平台。
5. 设置生产环境变量：ENONIC_API、ENONIC_APP_NAME、ENONIC_API_TOKEN、ENONIC_MAPPINGS。
6. 在 Enonic Cloud 中配置 Next.XP 应用，使其指向生产环境的 Next.js URL。
7. 在 Content Studio 中发布内容，使其显示在实时前端上。

步骤 7：验证集成

1. 执行 node scripts/find-nextxp-targets.mjs .，确认适配器、映射和环境配置仍能正确解析。
2. 验证独立 Next.js 渲染是否正常：在 http://localhost:3000 访问已发布的内容。
3. 验证 Content Studio 预览能否正确渲染草稿和已发布的内容。
4. 访问内容 URL，测试内容类型映射并确认自定义视图能够渲染。
5. 在页面处理程序中使用 @enonic/nextjs-adapter 的 validateData()，捕获无效的内容响应。页面静态生成（SSG）处理程序模式请参阅 references/nextxp-reference.md。
6. 运行工作区构建（npm run build），检查 TypeScript 或构建错误。

错误处理

• 如果 Content Studio 预览显示空白页面，请阅读 references/troubleshooting.md，了解预览代理诊断、令牌不匹配检测和 CORS 问题。
• 如果 Guillotine 查询返回空数据或意外数据，请确认内容类型名称与 introspection 模式匹配，并在 GraphQL Playground 中测试查询：http://localhost:8080/site/<project>。
• 如果导入 @enonic/nextjs-adapter 失败，请查看 references/compatibility.md 了解版本要求，并确认已安装该软件包。
• 如果内容在预览中能够渲染，但未显示在公开站点上，请确认内容已发布（已从 draft 分支移至 master 分支）。
• 如果组件映射未生效，请确认 _mappings.ts 中的注册使用了正确的、带 APP_NAME 的完全限定内容类型或组件名称。