GitHub Actions部署报错：node-sass安装失败，根源是Node和Python版本冲突

脚本专家

在利用GitHub Actions自动构建并部署Vue项目到GitHub Pages时，很多开发者会遇到node-sass安装失败的报错，错误码通常为1，且日志中反复出现node-gyp调用Python失败的信息。本文从实际报错日志入手，分析根因并给出两种可行的修复方案。

2. npm ERR! code 1
3. npm ERR! path /home/runner/work/CvReport/CvReport/node_modules/node-sass
4. npm ERR! command failed
5. npm ERR! command sh -c -- node scripts/build.js
6. npm ERR! Building: /usr/local/bin/node /home/runner/work/CvReport/CvReport/node_modules/node-gyp/bin/node-gyp.js rebuild --verbose --libsass_ext= --libsass_cflags= --libsass_ldflags= --libsass_library=
7. ...
8. npm ERR! gyp ERR! stack SyntaxError: Missing parentheses in call to 'print'. Did you mean print(...)?
9. ...

复制代码

报错日志中关键线索有两个：
- 错误出现在node-gyp尝试执行 `/usr/bin/python -c import sys; print "%s.%s.%s" % sys.version_info[:3];` 时，Python3抛出了SyntaxError，因为`print`在Python3中必须作为函数调用，而旧版node-gyp（3.8.0）生成的命令是Python2语法。
- 实际环境中检测到的是 `/usr/bin/python`（Python3），而node-gyp需要Python2。

更深层的原因：GitHub Actions的默认Ubuntu镜像中，`python`通常指向Python3，而node-sass依赖的node-gyp版本较老，编译时要求Python2。但直接根源是Node.js版本过高——当通过`actions/setup-node@v3`不指定版本时，会使用最新Node（如v16.18.1），而该Node版本对应的node-gyp版本（3.8.0）已不再适配Python3。本地开发使用Node v14.18.3可以正常安装，说明低版本Node搭配node-gyp版本兼容性更好。

解决方案分为两步：

1. 在GitHub Actions工作流中明确指定Node.js版本，避免使用最新版。
2. 可同时指定多个版本进行矩阵测试，确保至少一个版本能成功构建。

这是修正后的workflow示例（单版本）：

2. name: Node.js CI
3. on: [push]
4. jobs:
5.   build:
6.     runs-on: ubuntu-latest
7.     steps:
8.       - uses: actions/checkout@v3
9.       - name: Use Node.js
10.         uses: actions/setup-node@v3
11.         with:
12.           node-version: '12.x'
13.       - run: npm ci
14.       - run: npm run build --if-present
15.       - run: npm test

复制代码

如果需要测试多个版本，可以使用矩阵策略：

2. name: Node.js CI
3. on:
4.   push:
5.     branches: [ main ]
6.   pull_request:
7.     branches: [ main ]
8. jobs:
9.   build:
10.     runs-on: ubuntu-latest
11.     strategy:
12.       matrix:
13.         node-version: [10.x, 12.x, 14.x, 15.x]
14.     steps:
15.       - uses: actions/checkout@v3
16.       - name: Use Node.js ${{ matrix.node-version }}
17.         uses: actions/setup-node@v3
18.         with:
19.           node-version: ${{ matrix.node-version }}
20.       - run: npm ci
21.       - run: npm run build --if-present
22.       - run: npm test

复制代码

实际测试结果：Node 14.x版本成功构建，而Node 15.x失败。因此推荐使用与本地开发环境一致的Node版本（如14.x或12.x），避免使用v15及以上版本，直到相关依赖更新兼容。

另外，如果必须使用新版Node，还可以考虑切换到`dart-sass`替代`node-sass`，但这需要修改项目中的sass依赖配置，不在本文讨论范围。

总结：在GitHub Actions中自动化安装node-sass失败，通常是因为Actions默认使用了最新Node版本，导致node-gyp无法找到Python2或与Python3不兼容。通过显式设置`node-version`为稳定版本（如12.x、14.x），即可规避该问题。该思路同样适用于其他CI/CD环境（如Jenkins、GitLab CI），只要在构建前确保Node版本与本地开发一致即可。

热心网友5

感谢楼主分享这么详细的分析！最近我也在GitHub Actions里碰到过类似的node-sass报错，当时卡了好一阵子，只记得降Node版本能解决，但没深究到node-gyp和Python的兼容性层面。你从日志中`print`语法错误入手，把Python2/3冲突和Node版本连带影响串起来讲得很清楚，特别是提到node-gyp 3.8.0不再适配Python3这个关键点，让我对问题根因的理解又深了一层。矩阵测试的策略也很实用，既能验证哪个版本稳定，又不影响其他分支的构建。我之前只用单一版本，下次可以试试矩阵配置来提前发现问题。另外你提到的dart-sass替代方案虽然没展开，但也是个值得考虑的方向。总之非常感谢这篇实战排查经验，收藏了！