不能只备份package.json，因为它只是声明式快照；必须同步保留package-lock.json、.vscode配置、Node/npm版本及registry设置，否则依赖树、调试、格式化等均不可复现。
为什么不能只备份 package.json
直接复制 package.json 文件对环境还原毫无意义。它只是声明式快照，不是可执行状态：
- npm install 时若缺 package-lock.json，依赖树会随 npm 版本、registry 源、甚至系统平台（Windows/macOS/Linux）而不同；
- "typescript": "^5.4.0" 在 Node 18 和 Node 20 下可能装出 5.4.5 或 5.5.2，且子依赖版本完全不可控；
- 即使依赖一致，.vscode/launch.json 缺失会导致 F5 调试直接失败；settings.json 里没配 prettier，保存就格式崩坏；
- node_modules/ 绝对不要打包——体积大、含 native addon、跨平台不兼容，且 npm install 本就是重装它的唯一可靠方式。
tar 打包前必须校验的三个文件
真正要打包的是能触发可复现安装的最小必要集合，不是所有文件都值得塞进压缩包：
- package.json 和 package-lock.json 必须同时存在，且 package-lock.json 不能被 .gitignore 忽略；
- .vscode/ 目录下只保留实际生效的文件：launch.json（调试）、tasks.json（构建）、settings.json（工作区覆盖），删掉空的或已废弃的；
- 若项目用 ESM（"type": "module"），检查 launch.json 是否含 "runtimeArgs": ["--experimental-specifier-resolution=node"]，否则 Node 启动直接报错。
Linux/macOS 一键备份脚本怎么写
别用 GUI 压缩工具点来点去，终端一行命令就能生成带时间戳、可审计的归档：
- 运行：tar -czf workspace-backup-$(date +%Y%m%d-%H%M).tgz package*.json .vscode/；
- 补充校验：npm ls --depth=0 > deps-list.txt && tar -rf workspace-backup-$(date +%Y%m%d-%H%M).tgz deps-list.txt（人工核对顶层依赖）；
- 如果用了私有 registry，加一行：echo "registry: $(npm config get registry)" >> registry-info.txt && tar -rf ...；
- Windows 用户请改用 7-Zip 命令行：7z a -tzip workspace-backup-%date:~-4,4%%date:~-10,2%%date:~-7,2%.zip package*.json .vscode/（注意路径分隔符为 \）。
恢复后 npm install 失败的常见原因
解压完直接 npm install 就跑？大概率卡住或报错：
- 先确认 node -v 和 npm -v 是否匹配 package.json 中 engines 字段（比如 "node": ">=18.18.0"）；
- npm config get registry 输出是否为你预期的源（如 https://nexus.yourcompany.com/repository/npm/），不是默认 https://registry.npmjs.org/；
- Windows 上 npm run dev 报 cross-env: command not found？说明全局没装，得先 npm install -g cross-env，或把脚本改成 npx cross-env NODE_ENV=development ...；
- VS Code 启动后 launch.json 不生效？检查是否打开了项目根目录（不是子文件夹），且 .vscode/ 确实在该目录下，而非嵌套在 src/ 或 client/ 里。
备份不是存个文件，是固化一套可验证、可触发、可迁移的执行上下文。最容易被忽略的，永远是那些没写在 package.json 里却决定能否跑起来的东西：registry 配置、Node 版本约束、VS Code 工作区级设置路径、甚至 SSH 的 known_hosts 记录。
