本地运行没问题，提交后 CI 却失败，原因可能是 Node.js 版本不同、依赖安装方式不同，或者两边根本没跑同一条命令。让 Claude 帮你搭建流程时，不应先追求复杂矩阵和漂亮徽章，而应先把最小验证路径对齐。下面用一个零依赖项目说明，各文件都可以独立检查。
一 建立可解释的检查入口
创建项目文件 package.json：
{
"name": "check-parity-demo",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"test": "node --test",
"check": "node --check sum.mjs && npm test"
}
}
创建 sum.mjs：
export function sum(a, b) {
if (!Number.isSafeInteger(a) || !Number.isSafeInteger(b) ||
!Number.isSafeInteger(a + b)) {
throw new TypeError('输入与结果必须为安全整数');
}
return a + b;
}
创建 sum.test.mjs：
import test from 'node:test';
import assert from 'node:assert/strict';
import { sum } from './sum.mjs';
test('安全整数相加', () => assert.equal(sum(2, 3), 5));
test('拒绝字符串', () => assert.throws(() => sum('2', 3)));
test('拒绝溢出', () => assert.throws(() => sum(Number.MAX_SAFE_INTEGER, 1)));
在 .node-version 写入你已验证的确切 Node.js 版本。本例使用 24.19.0，这是本文本地实际运行的版本，不代表你的项目必须使用它。随后运行：
node --version npm --version npm install --package-lock-only --ignore-scripts --no-audit --no-fund npm ci --ignore-scripts --no-audit --no-fund npm run check
锁文件应进入版本控制。npm ci 文档说明了它对锁文件与清洁安装的要求。这里使用 --ignore-scripts 是因为演示项目没有依赖安装脚本；真实项目若需要原生模块构建，应先审查其安装行为，不能机械照搬。
二 把同一入口交给 GitHub Actions
在 .github/workflows/check.yml 中写入：
name: Check
on: [push, pull_request]
permissions:
contents: read
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
with:
node-version-file: .node-version
cache: npm
- run: npm ci --ignore-scripts --no-audit --no-fund
- run: npm run check
动作主版本对应核验时的 GitHub Node.js 工作流文档及官方动作说明。生产仓库若要求供应链锁定，应把审查过的动作固定到具体提交，并按团队流程更新；不要照抄来源不明的提交哈希。此流程不需要发布令牌，也没有部署步骤。
三 可复制的 Claude 提示词
请帮我对齐本地和 GitHub Actions 的验证流程。现有 package.json、锁文件状态、 Node/npm 版本、CI 日志如下：[粘贴脱敏内容]。 先比较运行时、安装命令、检查命令和环境变量的差异，再建议最小修复。 目标是本地与 CI 都运行 npm run check；不要新增发布、部署或仓库写权限。 请区分配置静态检查、本地实际运行、GitHub 远端实际运行，不能混称“CI 已通过”。 遇到失败请保留退出码，不要通过忽略错误或删除断言让状态变绿。
若项目已有构建、类型检查和测试脚本，让 Claude 把它们按清晰顺序接入既有入口，不要再造一个只在 CI 里存在的检查体系。
四 证明失败能被看见
本例的本地安装与 npm run check 已在 Node.js 24.19.0 中执行，三项测试通过；本文没有触发 GitHub 远端运行，不能据此宣称 CI 已通过。你首次提交后，应检查任务真正执行的版本、安装日志、测试数量和退出状态。
在练习分支把 sum(2, 3) 的预期值暂改为 6，本地命令应返回非零退出码；恢复后再运行。只有失败能挡住流程，绿色结果才有意义。缓存用于加速，不应替代锁文件；本地与 CI 命令相同也不保证浏览器、操作系统和外部服务完全一致，应把仍然存在的环境差异写进项目说明。
五 本地通过但远端失败时的排查顺序
先看失败发生在检出、安装还是测试，不要立即删除缓存。检出失败应检查引用和仓库设置；安装失败应比较锁文件、包管理器版本与需要的安装脚本；测试失败则保留完整命令和第一条有效报错，确认工作目录、文件名大小写及必需环境变量。不要把密钥值贴进对话，可以仅说明变量是否存在和用途。
本文统一了 Node.js 版本和检查入口，但没有固定所有环境因素。例如 npm 版本、操作系统镜像、外部服务和动作标签仍可能变化。需要更强可重复性时，逐项记录这些依赖，再按项目风险决定是否固定。不要为了“完全一致”而盲目冻结已停止维护的运行时，也不要因为一个缓存命中就判断安装过程可靠。
方法参考：Anthropic 提示工程概览。