如何通过CircleCI部署Angular应用到GitHub Pages？执行ngh报错退出码1

阿华AIGC实验室

2026-5-19

Hey there, let's work through that frustrating "Exited with code 1" error you're hitting when using angular-cli-ghpages (ngh) to deploy your Angular app to GitHub Pages via CircleCI. I've debugged this exact issue a few times, so here are the most likely fixes and debugging steps:

1. Make sure CircleCI has proper repo permissions

First up, confirm CircleCI has write access to your GitHub repository. Head to your CircleCI project settings, find the "Permissions" section, and ensure both "Checkout code" and "Write to repo" are enabled.
If you're using a Personal Access Token (PAT) for authentication, double-check that the token has the repo scope (including public_repo and repo:status) and that it's correctly set as an environment variable in CircleCI (usually named GH_TOKEN or GITHUB_TOKEN).

2. Validate your build and ngh command setup

Before running ngh, you must first build your Angular app for production with the correct base-href (this matches your GitHub Pages repo name). For example, if your repo is username/my-angular-app, your build command should look like:
```
ng build --prod --base-href="/my-angular-app/"
```
When executing ngh, specify the exact directory where your build output lives (you can find this path in angular.json under projects.[your-app-name].architect.build.options.outputPath). Add --no-silent or --verbose to get detailed logs:
```
npx angular-cli-ghpages --dir=dist/your-app-name --verbose
```

3. Fix Git configuration gaps in CircleCI

CircleCI's default checkout step doesn't set up Git user credentials, which ngh needs to commit changes to the gh-pages branch. Add these commands before running ngh to configure Git:
```
git config --global user.name "CircleCI"
git config --global user.email "circleci@example.com"
```
Ensure your repo has a gh-pages branch. If it doesn't, create it locally first and push it to GitHub, or let ngh create it automatically (this requires write permissions).

4. Check for dependency version conflicts

Outdated versions of angular-cli-ghpages can cause compatibility issues with newer Angular CLI versions. Update to the latest version:
```
npm install angular-cli-ghpages@latest --save-dev
```
Verify that your Angular CLI version aligns with the angular-cli-ghpages docs (Angular 15+ works best with the latest angular-cli-ghpages releases).

Full CircleCI Config Example

Here's a complete .circleci/config.yml that incorporates all these fixes:

version: 2.1
jobs:
  build-and-deploy:
    docker:
      - image: cimg/node:18.17.0 # Use a Node version compatible with your Angular app
    steps:
      - checkout
      - run: npm install
      - run: ng build --prod --base-href="/my-angular-app/"
      - run: |
          git config --global user.name "CircleCI"
          git config --global user.email "circleci@example.com"
      - run: npx angular-cli-ghpages --dir=dist/my-angular-app --verbose
workflows:
  deploy-to-gh-pages:
    jobs:
      - build-and-deploy:
          filters:
            branches:
              only: main # Trigger deployment only from the main branch

If after trying these steps you still get the error, the --verbose flag will show exactly where the command is failing—whether it's a missing directory, Git authentication issue, or something else.

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