GitHub Runner执行npx cdk遇语法错误的排查求助

核心报错原因 #

import: not found本质是shell环境与CDK脚本语法不兼容：npx临时拉取的CDK版本（默认是最新版）入口脚本用了ES模块语法，但GitHub Runner默认shell（如sh）会直接把它当shell脚本执行，而非交给Node.js处理，导致语法解析失败。而你本地项目.infra/node_modules/.bin/cdk是固定的2.93.0版本，它的入口脚本适配了当前环境的shell/Node.js写法，所以能正常运行。

排查方法与npx路径解析逻辑 #

1. 查看npx完整执行流程 #

执行命令查看npx如何查找、安装和执行CDK：

npx --verbose cdk --version

输出会显示：是否在本地node_modules查找包、是否下载临时版本、临时文件存储路径、执行时的环境变量等。你会发现npx的优先级是：全局安装包 → npm仓库拉取最新版到临时目录（通常在~/.npm/_npx/），不会默认使用项目本地的包，除非你指定目录。

2. 强制npx使用项目本地CDK #

要让npx调用项目里的CDK，有两种方式：

• 指定项目目录：

  npx --prefix .infra cdk --version
  

• 进入项目目录后执行：

  cd .infra && npx cdk --version
  

3. 验证临时CDK脚本的问题 #

手动检查npx临时安装的CDK入口脚本：

1. 用npx --verbose找到临时路径（比如/home/runner/.npm/_npx/xxxx/node_modules/aws-cdk/bin/cdk）
2. 查看文件首行的shebang（#!/usr/bin/env node），如果缺失或错误，shell会直接解析脚本里的import语句，导致报错。

本地CDK与npx临时CDK的差异原因 #

项目本地安装的aws-cdk@2.93.0：

• 入口脚本首行有正确的#!/usr/bin/env node，确保系统调用Node.js执行脚本，而非shell
• 该版本的CDK入口未使用shell不兼容的ES模块语法（或有兼容逻辑）

而npx临时拉取的新版本CDK：

• 可能改用了纯ES模块写法
• 入口脚本的shebang配置有误，导致GitHub Runner的shell无法正确识别并交给Node.js处理

长期解决办法 #

• 直接调用项目本地的CDK路径：./.infra/node_modules/.bin/cdk --version
• 在项目.infra/package.json中添加脚本（比如"cdk:version": "cdk --version"），用npm run cdk:version执行（npm会自动使用本地node_modules里的包）
• 如果必须用npx，指定具体版本避免拉取不兼容的最新版：npx aws-cdk@2.93.0 --version

内容的提问来源于stack exchange，提问作者Jun-Dai Bates-Kobashigawa