如何在GitHub Actions中正确传递Node测试脚本的命令行选项？

核心问题原因 #

你的npm脚本里把测试文件路径'test/**/*.test.js'直接写在了node --test之后，导致通过npm run传递的参数会被追加到整个命令的末尾，变成node --test 'test/**/*.test.js' --test-shard=...。而Node.js的命令行规则要求选项必须放在脚本/文件路径之前，所以这个分片参数被当成了测试脚本的参数而非Node.js的选项，自然被忽略。

具体解决方案 #

方案1：用环境变量注入Node.js选项 #

修改package.json中的脚本，预留环境变量位置用于注入Node.js的测试选项：

"scripts": {
  "test-hello": "node $NODE_TEST_OPTIONS --test 'test/**/*.test.js'"
}

然后在GitHub Actions工作流中设置环境变量，把分片参数传入：

- run: xvfb-run npm run test-hello
  env:
    NODE_TEST_OPTIONS: "--test-shard=${{ matrix.shard }}/4"

这种方式能确保Node.js选项被放在正确的位置，不会被文件路径截断。

方案2：调整脚本结构，让参数前置 #

如果希望保持通过npm run --传递参数的方式，可以修改npm脚本，让它接收的参数先传递给Node.js：

"scripts": {
  "test-hello": "node --test $@"
}

然后在工作流中同时传递分片参数和测试文件路径（注意顺序）：

- run: xvfb-run npm run test-hello -- --test-shard=${{ matrix.shard }}/4 'test/**/*.test.js'

这里$@会把npm run --后面的所有参数原样传递给node --test，确保选项在文件路径之前。

方案3：用shell变量动态调整参数 #

如果需要更灵活的参数控制，可以在脚本中使用shell变量：

"scripts": {
  "test-hello": "node ${TEST_FLAGS:-} --test 'test/**/*.test.js'"
}

${TEST_FLAGS:-}表示如果TEST_FLAGS环境变量不存在，就用空值。在Actions中设置：

- run: xvfb-run npm run test-hello
  env:
    TEST_FLAGS: "--test-shard=${{ matrix.shard }}/4"

GitHub Actions管理命令行参数的最佳实践 #

• 优先用环境变量传递复杂参数：避免命令行过长、转义错误，同时方便在多个步骤中复用参数。
• 明确npm参数传递规则：npm run <script> -- <args>中的--是用来把参数传递给npm脚本本身的，脚本内部必须正确处理这些参数的位置，否则会出现参数错位。
• 矩阵变量处理：使用${{ matrix.shard }}这类矩阵变量时，若变量包含特殊字符，要加双引号包裹，比如"--test-shard=${{ matrix.shard }}/4"。
• 本地预验证：在本地先运行npm run test-hello -- --test-shard=1/4验证参数是否生效，再部署到CI，减少调试成本。
• 复用参数定义：在工作流的env块中定义全局参数，比如：

  env:
    TEST_SHARD_FORMAT: "--test-shard=${{ matrix.shard }}/4"
  

  后续步骤直接引用，提升维护性。

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