使用cp -r复制Node.js/Angular项目后无法运行的原因

核心问题 #

复制Node.js或Angular项目时，直接用cp -r复制后大概率出现依赖找不到的错误，必须执行rm -rf node_modules && npm install才能正常运行，但Java项目用同样的复制操作却很稳定。

报错示例 #

Node.js项目报错 #

dean@Deans-MacBook-Pro server % ./node_modules/.bin/concurrently
node:internal/modules/cjs/loader:1222
  throw err;
  ^

Error: Cannot find module '../src/defaults'
Require stack:
- /Users/dean/workspace/biltup/biltup/server/node_modules/.bin/concurrently
    at Module._resolveFilename (node:internal/modules/cjs/loader:1219:15)
    at Module._load (node:internal/modules/cjs/loader:1045:27)
    at TracingChannel.traceSync (node:diagnostics_channel:315:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:215:24)
    at Module.require (node:internal/modules/cjs/loader:1304:12)
    at require (node:internal/modules/helpers:123:16)
    at Object.<anonymous> (/Users/dean/workspace/biltup/biltup/server/node_modules/.bin/concurrently:32:31)
    at Module._compile (node:internal/modules/cjs/loader:1504:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1588:10)
    at Module.load (node:internal/modules/cjs/loader:1282:32) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/Users/dean/workspace/biltup/biltup/server/node_modules/.bin/concurrently'
  ]
}

Node.js v22.5.0

Angular项目报错 #

dean@Deans-MacBook-Pro client % npm run dev

> fuse-angular@20.0.0 dev
> ng serve

node:internal/modules/cjs/loader:1222
  throw err;
  ^

Error: Cannot find module './bootstrap'
Require stack:
- /Users/dean/workspace/biltup/biltup/client/node_modules/.bin/ng
    at Module._resolveFilename (node:internal/modules/cjs/loader:1219:15)
    at Module._load (node:internal/modules/cjs/loader:1045:27)
    at TracingChannel.traceSync (node:diagnostics_channel:315:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:215:24)
    at Module.require (node:internal/modules/cjs/loader:1304:12)
    at require (node:internal/modules/helpers:123:16)
    at Object.<anonymous> (/Users/dean/workspace/biltup/biltup/client/node_modules/.bin/ng:70:3)
    at Module._compile (node:internal/modules/cjs/loader:1467:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1551:10)
    at Module.load (node:internal/modules/cjs/loader:1282:32) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/Users/dean/workspace/biltup/biltup/client/node_modules/.bin/ng' ]
}

Node.js v22.4.0

原因分析 #

1. 路径关联性问题：Node.js依赖包中的可执行文件（比如concurrently、ng）会包含基于原安装目录的相对路径或绝对路径引用。复制项目时这些路径不会自动更新，导致找不到对应模块文件。而Java项目依赖的jar包通过类路径加载，不依赖安装时的绝对路径。

2. 软链接失效：部分npm包会创建软链接指向其他模块或系统工具，直接复制时软链接可能因指向原目录不存在、跨文件系统复制被转为普通文件等原因失效，引发依赖加载失败。

3. 平台相关编译文件：node_modules中可能包含针对当前操作系统、CPU架构编译的二进制文件（如node-sass、sharp这类原生模块），复制到不同环境甚至同一机器的不同路径时，这些编译文件无法适配，导致加载错误。Java的jar包是跨平台字节码，不存在此问题。

4. 依赖树不匹配：若复制的项目未包含package-lock.json（或yarn.lock），或原项目安装依赖的npm/yarn版本与当前环境不一致，直接复制node_modules会导致依赖树不匹配，出现模块缺失。

解决办法 #

1. 避免直接复制node_modules：复制时排除该目录，只复制源码、package.json、package-lock.json（或yarn.lock），再在目标目录执行安装命令：

   # 复制时排除node_modules
   cp -r --exclude=node_modules source_dir/ target_dir/
   # 进入目标目录安装依赖
   cd target_dir && npm install
   

2. 彻底清理重装：若已复制node_modules出现错误，执行以下命令彻底重置依赖：

   rm -rf node_modules package-lock.json
   npm cache clean --force
   npm install
   

3. 用rsync处理软链接（可选）：如果需要保留软链接，用rsync替代cp，它能正确处理软链接：

   rsync -av --exclude=node_modules source_dir/ target_dir/
   

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