请求指导Strapi部署至cPanel的正确流程及错误解决方法

问题排查思路 #

• 删除本地上传的node_modules：本地环境和共享主机的系统架构、Node版本大概率不一致，直接上传的依赖包会出现兼容性问题，是报错的核心原因之一。
• 核对Node.js版本：Strapi对Node版本有明确要求（比如v4需要16.x/18.x/20.x），检查cPanel创建Node应用时选择的版本是否匹配项目package.json中engines字段的要求。
• 查看详细错误日志：不要仅依赖前端截图，在cPanel的「Node.js应用」中找到对应项目的日志入口，查看具体报错信息，定位是依赖安装失败、数据库连接错误还是启动脚本问题。
• 验证app.js配置：确保app.js的启动逻辑正确，标准的Strapi启动代码如下：

const strapi = require('@strapi/strapi');
strapi().start();

正确部署步骤 #

1. 本地项目预处理 #

• 确认本地项目能正常运行，将Strapi升级到对应稳定版本。
• 配置生产环境数据库：修改config/env/production/database.js（或根目录config/database.js），填入cPanel创建的MySQL数据库信息：

module.exports = ({ env }) => ({
  connection: {
    client: 'mysql',
    connection: {
      host: env('DATABASE_HOST', 'localhost'),
      port: env.int('DATABASE_PORT', 3306),
      database: env('DATABASE_NAME', 'your_db_name'),
      user: env('DATABASE_USERNAME', 'your_db_user'),
      password: env('DATABASE_PASSWORD', 'your_db_pass'),
      ssl: env.bool('DATABASE_SSL', false),
    },
  },
});

• 配置服务器参数：修改config/env/production/server.js，设置允许外部访问：

module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
  },
});

• 执行npm run build生成生产构建文件（build目录）。
• 打包项目文件：将package.json、package-lock.json、build、config、src、public等必要文件打包（排除node_modules、.git、.env.local等本地文件）。

2. cPanel端操作 #

• 创建MySQL数据库：在cPanel的「MySQL数据库向导」中创建数据库、数据库用户，并为用户分配全权限，记录好数据库名、用户名、密码。
• 创建Node应用：进入「Node.js应用」工具，选择符合要求的Node版本，设置应用根目录（如public_html/strapi），启动文件指定为app.js。
• 上传项目文件：将本地打包的文件上传到cPanel的应用根目录。
• 安装依赖：在「Node.js应用」中点击「运行NPM安装」，等待依赖安装完成（若安装失败，根据日志提示排查，比如缺少构建工具可联系主机商开启）。
• 设置环境变量：在「Node.js应用」的环境变量配置中，添加生产所需变量：
  • NODE_ENV=production
  • DATABASE_HOST=localhost
  • DATABASE_NAME=你的数据库名
  • DATABASE_USERNAME=你的数据库用户名
  • DATABASE_PASSWORD=你的数据库密码
  • APP_KEYS（从本地.env文件复制）
  • ADMIN_JWT_SECRET（从本地.env文件复制）
• 启动应用：点击「启动应用」，查看日志确认启动成功。
• 绑定域名（可选）：在cPanel的「域名」工具中设置反向代理，将域名指向Node应用的端口。

内容的提问来源于stack exchange，提问作者Mohammad jadid