ng command not found? Jak naprawić Angular CLI

Terminal zatrzymuje pracę, zanim powstanie choć jedna linia aplikacji, bo polecenie Angular CLI nie zostaje odnalezione. Komunikat ng command not found zwykle oznacza brak Angular CLI, nieprawidłowy katalog w zmiennej PATH albo problem z instalacją Node.js. Pokażę, jak rozpoznać konkretną przyczynę i naprawić ją na Windowsie, macOS oraz Linuksie.

Co naprawdę oznacza brak polecenia ng

ng to skrót od Angular CLI, czyli narzędzia używanego do tworzenia, uruchamiania, budowania i testowania aplikacji Angular. Pakiet @angular/cli instaluje program wykonywalny, który terminal powinien znaleźć dzięki zmiennej środowiskowej PATH.

Gdy pojawia się komunikat o nierozpoznanym poleceniu, problem najczęściej leży w jednej z trzech rzeczy. Angular CLI nie jest zainstalowane, zostało zainstalowane w innym środowisku Node.js albo katalog z globalnymi pakietami npm nie znajduje się w PATH.

To ważne rozróżnienie. Sam projekt Angulara może mieć poprawne pliki w katalogu node_modules, a mimo to globalne polecenie nie zadziała. Z drugiej strony globalne ng może działać, ale uruchamiać wersję niepasującą do konkretnego projektu.

Najpierw sprawdź Node.js, npm i miejsce instalacji

Zanim ponownie zainstalujesz Angular CLI, sprawdź, czy terminal widzi Node.js oraz npm. Wykonaj:

node --version
npm --version

Jeśli oba polecenia zwracają numery wersji, podstawowe środowisko jest dostępne. Jeżeli pojawia się podobny błąd jak przy ng, problem dotyczy instalacji Node.js albo konfiguracji PATH, a nie Angulara.

Przydatne jest również sprawdzenie katalogu, w którym npm umieszcza globalne pakiety:

npm prefix --global

Na macOS i Linuksie wykonywalne pliki globalnych pakietów zwykle trafiają do katalogu bin wewnątrz tego miejsca. Na Windowsie często korzystają z katalogu npm w profilu użytkownika. Nie zakładaj jednak z góry konkretnej ścieżki, ponieważ może się ona różnić przy użyciu nvm, nvm-windows, instalatora Node.js lub menedżera pakietów.

Samą lokalizację polecenia możesz sprawdzić systemowo:

# macOS i Linux
command -v ng

# Windows CMD
where ng

# PowerShell
Get-Command ng

Brak wyniku oznacza, że bieżąca powłoka nie potrafi znaleźć programu. Wynik wskazujący starą instalację jest równie cenną informacją, bo często ujawnia konflikt kilku wersji Node.js.

Zainstaluj Angular CLI w sposób dopasowany do projektu

Jeśli Angular CLI nie jest zainstalowane, podstawowa instalacja globalna wygląda tak:

npm install --global @angular/cli

Po zakończeniu instalacji zamknij terminal, otwórz go ponownie i sprawdź:

ng version

Dokumentacja Angulara wskazuje również pnpm, Yarn i Bun jako alternatywne menedżery pakietów. Najważniejsze jest zachowanie jednego sposobu instalacji w całym zespole, bo mieszanie kilku menedżerów utrudnia ustalenie, skąd faktycznie pochodzi uruchamiane polecenie.

W nowym projekcie możesz użyć globalnego CLI:

ng new moja-aplikacja
cd moja-aplikacja
ng serve --open

Jeśli pracujesz już w istniejącym repozytorium, sprawdź plik package.json. Gdy znajduje się w nim @angular/cli w sekcji devDependencies, nie musisz instalować kolejnej wersji globalnie. Uruchom lokalny program przez:

npx ng version
npx ng serve

npx korzysta z wersji dostępnej w projekcie, dlatego jest bezpieczniejszym wyborem przy kilku aplikacjach Angular wymagających różnych wersji CLI. Globalne ng traktuję raczej jako wygodę do tworzenia nowych projektów niż źródło wersji używanej w produkcyjnym repozytorium.

Napraw PATH i typowe problemy systemowe

Windows i PowerShell

Na Windowsie instalacja może zakończyć się poprawnie, ale stare okno terminala nadal nie zna nowej ścieżki. Najprostszy test to ponowne uruchomienie PowerShella, CMD albo terminala w edytorze. Jeśli nadal nie ma wyniku, sprawdź ścieżkę globalnych pakietów poleceniem npm prefix --global i upewnij się, że właściwy katalog z plikami wykonywalnymi znajduje się w PATH.

PowerShell może też blokować skrypty uruchamiane przez npm. W takim przypadku Angular zaleca ustawienie polityki dla bieżącego użytkownika:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Nie zmieniaj polityki dla całego systemu bez potrzeby. Zakres CurrentUser ogranicza zmianę do Twojego konta i zwykle wystarcza do pracy z globalnymi poleceniami npm.

macOS i Linux

Na systemach Unixowych częstym problemem jest instalacja globalna wykonana przez sudo albo użycie innej wersji Node.js niż ta aktywna w bieżącej sesji. Błąd uprawnień przy instalacji nie oznacza, że najlepszym rozwiązaniem jest stałe używanie sudo npm install -g.

Lepszą kontrolę daje menedżer wersji Node.js, na przykład nvm. Pozwala przełączać wersje Node.js razem z npm i ogranicza konflikty uprawnień, szczególnie gdy pracujesz nad projektami Angular, aplikacjami .NET oraz narzędziami Azure na tym samym komputerze.

Przeczytaj również: var w JavaScripcie - zakres, hoisting i pułapki starego kodu

Uszkodzona lub podwójna instalacja Node.js

Jeżeli node --version i npm --version działają, ale instalacja CLI nie daje rezultatu, sprawdź, czy masz więcej niż jedną instalację Node.js. Taki konflikt pojawia się po przejściu z instalatora na nvm albo po aktualizacji Node bez usunięcia starszej wersji.

Wynik poleceń where node na Windowsie lub which node na macOS i Linuksie pokaże, z którego miejsca uruchamiany jest Node. Jedna aktywna instalacja jest łatwiejsza do diagnozowania niż kilka katalogów konkurujących o pierwszeństwo w PATH.

Globalne ng czy lokalne npx

Oba sposoby są poprawne, ale rozwiązują nieco inny problem. Poniższe zestawienie pomaga szybko wybrać właściwe podejście:

W praktyce najczęściej instaluję CLI globalnie, aby szybko utworzyć workspace, a po wejściu do repozytorium korzystam z wersji lokalnej. Dzięki temu aktualizacja globalnego narzędzia nie zmienia przypadkiem zachowania starszego projektu.

Jeżeli lokalne npx ng działa, a samo ng nie, projekt jest prawdopodobnie zdrowy. Nie ma wtedy potrzeby przebudowywać node_modules ani usuwać pliku blokady zależności. Wystarczy używać lokalnej wersji albo poprawić globalną konfigurację.

Gdy instalacja działa, ale projekt nadal zgłasza błąd

Po naprawieniu dostępności polecenia możesz natrafić na drugi, niezależny problem. Angular CLI wymaga obsługiwanej wersji Node.js, a konkretne wydanie Angulara ma własne wymagania kompatybilności. Dlatego po instalacji sprawdź:

ng version
npm list --depth=0
cat package.json

Na Windowsie zamiast cat możesz użyć Get-Content package.json. Interesują Cię przede wszystkim wersje Angulara, Angular CLI, Node.js oraz menedżera pakietów. Nie aktualizuj wszystkich zależności w ciemno, jeśli celem jest tylko usunięcie błędu z poleceniem.

Jeśli pracujesz w istniejącym projekcie, uruchamiaj komendy takie jak ng generate czy ng serve z katalogu workspace, czyli miejsca zawierającego plik angular.json. Polecenie ng new działa odwrotnie, ponieważ tworzy nowy workspace i zwykle uruchamia się je poza jego katalogiem.

W środowisku CI lub Dockerze globalna instalacja często nie jest potrzebna. Stabilniejszy przebieg zapewnia instalacja zależności z pliku blokady i uruchamianie skryptów projektu przez npm. To ogranicza różnice między komputerem programisty a serwerem budującym aplikację.

Krótka procedura, która zwykle rozwiązuje problem

1. Sprawdź node --version oraz npm --version.
2. Uruchom npm prefix --global i zweryfikuj lokalizację globalnych pakietów.
3. Zainstaluj CLI poleceniem npm install --global @angular/cli.
4. Otwórz nowe okno terminala.
5. Potwierdź działanie przez ng version.
6. W istniejącym projekcie sprawdź także npx ng version.
7. Jeśli globalne polecenie nadal nie działa, popraw PATH albo uporządkuj wiele instalacji Node.js.

Najczęściej problem kończy się na instalacji Angular CLI i ponownym uruchomieniu terminala. Jeżeli jednak działa tylko wersja lokalna, potraktuj to jako użyteczną wskazówkę, a nie awarię. Dla konkretnego projektu zgodność wersji z jego package.json jest ważniejsza niż samo globalne polecenie.