CPanel部署Puppeteer脚本报SyntaxError的排查解决方法

• 本地可正常运行的Puppeteer脚本：功能为爬取油价、汇率类数值数据后写入MySQL，需要部署到Namecheap cPanel主机实现每日定时运行
• 当前故障：已在cPanel安装Node.js应用，但运行时触发两个核心异常
  • 脚本首行import puppeteer from 'puppeteer';抛出SyntaxError: Unexpected identifier
  • 运行时提示npm与node二进制路径不匹配
• 已附完整报错日志、Node.js应用配置截图、全量业务代码

1. ES模块解析失败：要么是当前运行的Node版本低于v14（v12及更早版本对ESM语法仅提供实验性支持，默认不识别import关键字），要么是项目未声明ESM模式，Node默认按CommonJS规范解析.js文件，碰到import语法直接报标识符错误。
2. 环境路径不匹配：cPanel的Node.js应用是按项目做虚拟环境隔离的，SSH默认调用的全局node/npm是系统预装版本，和你在cPanel面板为当前应用选定的Node版本不在同一路径，装依赖、跑脚本时调用错二进制就会触发该警告，还会出现依赖已安装但运行时找不到的问题。
3. 额外注意：默认Puppeteer包自带的Chromium无法在cPanel共享主机直接运行，共享主机无root权限安装Chromium依赖的系统库，这是后续大概率触发的故障点。

1. 解决路径不匹配问题 #

• 登录cPanel进入「Setup Node.js App」页面，找到已创建的应用点击编辑，记录下页面显示的应用根目录、选定的Node版本（建议切换到v18及以上LTS版本，不要选v16以下版本）
• 连接SSH进入服务器，直接复制Node.js应用编辑页顶部给出的虚拟环境激活命令执行，命令格式参考如下，替换成你自己的账号信息即可：

  source /home/你的cPanel用户名/nodevenv/项目根目录名/选定的Node版本号/bin/activate && cd /home/你的cPanel用户名/项目根目录名
  

• 激活后执行node -v、npm -v，确认输出版本和面板选定版本一致，后续所有装依赖、跑脚本的操作，都必须先激活该虚拟环境再执行，禁止直接调用全局node/npm。

2. 修复import语法报错 #

两种方案选其一即可，推荐第一种不用改业务代码：

• 方案1（保留原有import写法）：
  打开项目根目录的package.json，在最外层配置项添加"type": "module"，示例如下：

  {
    "type": "module",
    // 原有name、scripts、dependencies等配置全部保留不动
  }
  

• 方案2（兼容低版本Node）：
  把脚本中所有import 变量 from '包名'的写法替换为CommonJS规范的const 变量 = require('包名')，比如首行替换为const puppeteer = require('puppeteer');。

3. 修复Puppeteer运行兼容问题 #

不要安装默认的puppeteer包，卸载后换装puppeteer-core（不带内置Chromium，直接调用主机预装的Chromium）：

npm uninstall puppeteer
npm install puppeteer-core mysql2

修改脚本中Puppeteer启动配置，指定主机Chromium路径并添加共享主机必需的启动参数：

const browser = await puppeteer.launch({
  executablePath: '/usr/bin/chromium-browser',
  args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
  headless: 'new'
});

4. 配置每日定时运行 #

• 先在激活虚拟环境的状态下手动执行脚本，确认爬取、写库全流程正常无报错：

  node 你的脚本文件名.js
  

• 回到cPanel主页找到「Cron Jobs」功能，设置运行频率为每日1次（建议选低峰时段比如凌晨2点），命令栏填写虚拟环境内node二进制的绝对路径+脚本绝对路径，格式参考：

  /home/你的cPanel用户名/nodevenv/项目根目录名/选定的Node版本号/bin/node /home/你的cPanel用户名/项目根目录名/你的脚本文件名.js
  

  注意不要直接写node 脚本路径，必须用绝对路径，否则定时任务运行时找不到对应依赖环境。

如果仍有报错，先在激活虚拟环境后执行which node和which npm，确认输出路径在当前项目对应的nodevenv目录下，而非/usr/bin/下的全局版本；其次确认所有依赖都安装在项目本地的node_modules目录，无漏装。

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