通过GitLab CI使用Capistrano部署Angular 5应用遇npm构建问题

我来帮你捋捋这个部署坑——之前用Capistrano部署前端项目时也碰到过类似的node_modules为空、构建失败的情况，给你几个排查方向和具体的解决办法：

1. 先确认Capistrano任务的执行路径与权限 #

Capistrano默认会在远程服务器的release_path（每次部署的新版本目录）下操作，首先检查你的npm_install.cap是否正确指定了工作目录：

namespace :npm do
  desc 'Install npm dependencies'
  task :install do
    on roles(:app) do
      # 必须在release目录下执行npm install，不然依赖会装到错误路径
      within release_path do
        # 如果是生产环境可以加--production，开发环境去掉
        execute :npm, 'install', '--verbose'
      end
    end
  end
end

同时要确认远程服务器上的部署用户对release_path目录有读写权限，不然npm无法创建node_modules目录，可能静默失败。

2. 验证Node.js与npm版本兼容性 #

Angular 5对Node版本有严格要求（推荐Node 8.x系列，npm 5.x左右），不管是GitLab CI Runner还是远程服务器，版本不匹配都会导致npm install失败但无明显报错：

• 在GitLab CI的.gitlab-ci.yml里加版本检查：

  before_script:
    - node -v
    - npm -v
  

• 在Capistrano任务里也可以加版本验证，确保远程环境符合要求：

  execute :node, '-v'
  execute :npm, '-v'
  

如果版本不对，建议用nvm管理远程服务器的Node版本，在deploy.rb里配置环境变量：

set :default_env, {
  'PATH' => '$HOME/.nvm/versions/node/v8.17.0/bin:$PATH'
}

3. 查看npm install的详细日志 #

默认npm install的输出很简略，失败了可能只字不提，一定要加--verbose参数（上面的任务里已经加了），然后去GitLab CI的输出日志里找具体报错：

• 有没有网络问题？比如npm源无法访问，可以临时换成国内源：npm install --registry=https://registry.npmmirror.com --verbose
• 有没有依赖包版本冲突？比如package.json里的依赖版本不兼容Angular 5
• 有没有权限问题？比如远程服务器的npm需要sudo，但Capistrano默认不执行sudo命令（如果必须用，要配置execute :sudo, :npm, 'install'）

4. 确认Capistrano部署钩子的执行顺序 #

要确保npm install在代码拉取完成后、Angular构建前执行，在deploy.rb里正确设置钩子：

# 代码拉取并解压完成后执行npm install
after 'deploy:updated', 'npm:install'
# 构建完成后再完成部署收尾
before 'deploy:finished', 'angular:build'

同时检查你的build.cap是否在正确路径执行ng build：

namespace :angular do
  desc 'Build Angular app for production'
  task :build do
    on roles(:app) do
      within release_path do
        # Angular 5的生产构建用--prod参数
        execute :ng, 'build', '--prod'
      end
    end
  end
end

5. 排查GitLab CI Runner的环境问题 #

如果是在GitLab CI里触发Capistrano部署，还要确认：

• Runner能正常SSH连接到远程服务器，部署密钥配置正确
• Runner本身的Node环境是否符合要求？比如用Docker镜像的话，要选包含Node 8.x的镜像，比如node:8-alpine

先从查看npm install的详细日志入手，大部分情况都是版本不兼容、路径错误或者权限问题导致的，按上面的步骤排查应该能解决。

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