Coolify部署Payload CMS V3与Next.js 15的构建问题解析

在基于Coolify平台部署Payload CMS V3（使用Next.js 15作为前端框架）时，开发者可能会遇到一个特定的构建错误。本文将深入分析该问题的成因，并提供详细的解决方案。

问题现象

当使用Nixpacks构建工具在Coolify环境中部署应用时，构建过程会在编译阶段失败，并输出多个"Unexpected end of JSON input"错误。这些错误主要出现在以下模块中：

• @payloadcms/richtext-lexical
• @payloadcms/ui
• @radix-ui/react-dialog
• @radix-ui/react-select

错误表明Webpack在处理这些模块时遇到了JSON解析问题，最终导致构建失败。

根本原因分析

经过技术分析，这类问题通常由以下几个因素共同导致：

1. Node.js版本不匹配：Payload CMS V3和Next.js 15对Node.js版本有特定要求，使用不兼容的版本会导致模块解析异常。

2. 依赖缓存问题：构建过程中的缓存可能包含损坏或不完整的依赖项，特别是在跨环境部署时。

3. 模块解析冲突：当多个依赖项对同一模块有不同版本要求时，可能会引发解析异常。

解决方案

1. 确保使用正确的Node.js版本

在Coolify部署配置中，明确指定使用Node.js 20版本。这可以通过设置构建环境变量实现：

NIXPACKS_NODE_VERSION=20

这个变量应该作为构建变量添加到Coolify的部署配置中，确保Nixpacks使用正确的Node.js版本进行构建。

2. 更新依赖项

确保所有Payload CMS相关依赖都更新到最新版本：

@payloadcms/richtext-lexical: 3.16.0或更高
@payloadcms/ui: 3.16.0或更高

Payload团队在较新版本中修复了与编辑器相关的已知问题，更新依赖可以避免已知的兼容性问题。

3. 执行干净构建

在Coolify中执行部署时，选择"Clean Deploy"选项，这将确保：

• 不使用任何缓存依赖
• 从头开始完整构建应用
• 避免残留的构建产物干扰

4. 验证构建环境

检查Coolify服务器的资源分配情况，确保：

• 有足够的内存处理构建过程
• 磁盘空间充足
• 网络连接稳定

资源不足可能导致构建过程中断，进而产生不完整的模块文件。

预防措施

为了避免类似问题再次发生，建议：

1. 在本地开发环境中使用与生产环境相同的Node.js版本
2. 定期更新项目依赖项
3. 在CI/CD流程中加入版本检查步骤
4. 考虑使用.nvmrc或engines字段明确指定Node.js版本要求

通过以上措施，可以显著提高在Coolify平台上部署Payload CMS应用的稳定性，确保构建过程顺利完成。