Bezpieczne procedury aktualizacji

Aktualizacja Claude Code wymaga starannego planowania i wykonania, szczególnie w środowiskach zespołowych lub korporacyjnych. Ten przewodnik przedstawia kompleksowe procedury bezpiecznych, niezawodnych aktualizacji z minimalnym zakłóceniem przepływu pracy.

Zrozumienie ścieżek aktualizacji

Auto-aktualizacje (domyślnie)

Bezproblemowe aktualizacje w tle bez przestojów - zalecane dla większości użytkowników

Aktualizacje ręczne

Pełna kontrola nad czasem i testowaniem - idealne dla zespołów i przedsiębiorstw

Przypięcie wersji

Zablokowanie określonych wersji dla stabilności - wymagane w regulowanych środowiskach

Gotowość do cofnięcia

Zawsze utrzymuj możliwość powrotu - krytyczne dla środowisk produkcyjnych

Lista kontrolna przed aktualizacją

Przed każdą aktualizacją upewnij się, że jesteś przygotowany:

1. Sprawdź bieżącą wersję

   claude --version
   claude doctor  # Bardziej szczegółowa diagnostyka

2. Przejrzyj informacje o wydaniu

   # Wewnątrz Claude Code
   /release-notes
   
   # Lub sprawdź GitHub
   # github.com/anthropics/claude-code/releases

3. Wykonaj kopię zapasową krytycznych konfiguracji

   # Kopia zapasowa konfiguracji
   cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d)
   cp -r .claude .claude.backup.$(date +%Y%m%d)

4. Przetestuj w środowisku niekrytycznym

   • Użyj najpierw projektu testowego
   • Zweryfikuj, czy główne przepływy pracy nadal działają
   • Sprawdź niestandardowe komendy i hooki

5. Powiadom członków zespołu

   • Przekaż harmonogram aktualizacji
   • Podziel się wszelkimi przełomowymi zmianami
   • Skoordynuj czas dla minimalnego zakłócenia

Procedury aktualizacji według typu instalacji

Instalacja globalna NPM

Standardowa aktualizacja

# Sprawdź dostępne aktualizacje
npm outdated -g @anthropic-ai/claude-code

# Wykonaj aktualizację
npm update -g @anthropic-ai/claude-code

# Zweryfikuj aktualizację
claude --version

Czysta instalacja

# Czasami potrzebne dla dużych skoków wersji
npm uninstall -g @anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code

Określona wersja

# Przypnij do określonej wersji
npm install -g @anthropic-ai/claude-code@1.0.54

# Zweryfikuj dokładną wersję
npm list -g @anthropic-ai/claude-code

Wskazówka

Problemy z uprawnieniami? Jeśli aktualizacja npm kończy się błędami uprawnień, rozważ migrację do instalacji lokalnej:

claude install

Instalacja lokalna (zalecana)

Metoda instalacji lokalnej unika problemów z uprawnieniami i zapewnia płynniejsze aktualizacje:

# Jeśli jeszcze nie dokonałeś migracji
claude install

# Aktualizacje następują automatycznie lub ręcznie
claude update

# Sprawdź lokalizację instalacji
which claude  # Powinno pokazać ~/.claude/local/claude

Instalacja natywnego pliku binarnego (Alpha)

Aktualizacja pliku binarnego

# Z istniejącej instalacji
claude install

# Lub świeża instalacja
curl -fsSL claude.ai/install.sh | bash

Uwagi o platformach

• macOS: Uniwersalny plik binarny, działa na Intel i Apple Silicon
• Linux: Automatyczne wykrywanie architektury
• Windows: Użyj WSL dla instalacji binarnej

Obsługa przełomowych zmian

Przykład: Zmiana formatu ARN Bedrock (v0.2.125)

Podczas aktualizacji przez przełomowe zmiany, postępuj według tego schematu:

1. Zidentyfikuj zmianę

   • Stary format: arn:aws:bedrock:region::foundation-model/model%2Fversion
   • Nowy format: arn:aws:bedrock:region::foundation-model/model/version

2. Zaktualizuj konfigurację

   # Przed aktualizacją, zaktualizuj zmienne środowiskowe
   export ANTHROPIC_MODEL="arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-opus-4.5-20240229-v1:0"
   # Uwaga: Brak %2F, użyj literalnego /

3. Przetestuj konfigurację

   # Zweryfikuj, czy konfiguracja działa
   claude doctor

4. Kontynuuj aktualizację

   claude update

Typowe kategorie przełomowych zmian

Format konfiguracji

Zmiany struktury JSON, nowe wymagane pola, przestarzałe opcje

Zmiany API

Zmiany nazw pól SDK (np. total_cost → total_cost_usd)

Zmiany nazw narzędzi

Wbudowane narzędzia otrzymują jaśniejsze nazwy (np. LSTool → LS)

Zmiany komend

Slash komendy lub flagi zmodyfikowane lub przestarzałe

Strategia aktualizacji korporacyjnej

Kontrola wersji i testowanie

• Folderinfrastructure/

  • Folderclaude-code/

    • versions.json (zatwierdzone wersje)
    • Foldertest-suite/ (walidacja aktualizacji)

      • …
    • Folderrollback-scripts/

      • …
• Folderdocumentation/

  • upgrade-log.md
  • known-issues.md

Proces wdrażania etapowego

1. Środowisko deweloperskie

   • Testuj z ochotniczymi programistami
   • Uruchom przez 1-2 dni
   • Zbierz opinie

2. Środowisko stagingowe

   • Szersza grupa testowa
   • Pełna walidacja przepływu pracy
   • Benchmarking wydajności

3. Wdrożenie produkcyjne

   • Komunikuj przez kanały zespołowe
   • Stopniowo według zespołu/regionu
   • Monitoruj problemy

4. Przegląd po aktualizacji

   • Zbierz opinie zespołu
   • Dokumentuj wszelkie problemy
   • Aktualizuj procedury

Zarządzanie konfiguracją korporacyjną

# Wyłącz auto-aktualizacje w całej firmie
export DISABLE_AUTOUPDATER=1

# Przypinanie wersji w package.json
{
  "devDependencies": {
    "@anthropic-ai/claude-code": "1.0.54"
  }
}

# Zautomatyzowany skrypt wdrażania
#!/bin/bash
APPROVED_VERSION="1.0.54"
CURRENT_VERSION=$(claude --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')

if [ "$CURRENT_VERSION" != "$APPROVED_VERSION" ]; then
  npm install -g @anthropic-ai/claude-code@$APPROVED_VERSION
fi

Procedury cofnięcia

Gdy aktualizacja powoduje problemy, szybkie cofnięcie jest niezbędne:

Natychmiastowe cofnięcie

Metoda NPM

# Cofnij do poprzedniej wersji
npm install -g @anthropic-ai/claude-code@1.0.53

# Przywróć kopię zapasową konfiguracji
rm -rf ~/.claude
mv ~/.claude.backup.20250716 ~/.claude

Instalacja lokalna

# Instalacje lokalne utrzymują historię wersji
cd ~/.claude/versions

# Wyświetl dostępne wersje
ls -la

# Przełącz na poprzednią wersję
ln -sf 1.0.53 current

Lista kontrolna cofnięcia

• ☐ Zatrzymaj wszystkie działające instancje Claude Code
• ☐ Przywróć poprzednią wersję
• ☐ Przywróć kopie zapasowe konfiguracji
• ☐ Wyczyść wszelki uszkodzony cache/stan
• ☐ Zweryfikuj funkcjonalność
• ☐ Dokumentuj problemy dla raportu błędów

Weryfikacja po aktualizacji

Po każdej aktualizacji zweryfikuj krytyczną funkcjonalność:

1. Podstawowa funkcjonalność

   # Sprawdź wersję i diagnostykę
   claude --version
   claude doctor
   
   # Przetestuj podstawową interakcję
   claude "Cześć, czy działasz prawidłowo?"

2. Integralność konfiguracji

   # Zweryfikuj zachowane ustawienia
   cat ~/.claude/settings.json
   
   # Sprawdź niestandardowe komendy
   ls .claude/commands/

3. Funkcjonalność narzędzi

   # Przetestuj operacje na plikach
   claude "Wyświetl pliki w bieżącym katalogu"
   
   # Przetestuj serwery MCP
   /mcp list

4. Sprawdzenie wydajności

   • Czas odpowiedzi
   • Użycie pamięci
   • Obsługa kontekstu

Rozwiązywanie typowych problemów z aktualizacją

Uszkodzenie konfiguracji

Uwaga

Jeśli Claude Code nie uruchamia się po aktualizacji, często przyczyną jest uszkodzenie konfiguracji.

# Diagnozuj problemy z konfiguracją
claude doctor

# Zresetuj do wartości domyślnych, jeśli potrzeba
mv ~/.claude/config.json ~/.claude/config.json.backup
claude # Odtworzy z wartościami domyślnymi

Błędy uprawnień

# Problemy z uprawnieniami NPM
sudo npm install -g @anthropic-ai/claude-code  # Niezalecane

# Lepsze rozwiązanie: migruj do lokalnej
claude install

Konflikty wersji

# Sprawdź wielokrotne instalacje
which -a claude
type -a claude

# Usuń duplikaty
npm uninstall -g @anthropic-ai/claude-code
# Następnie zainstaluj ponownie

Kompatybilność serwera MCP

Po głównych aktualizacjach serwery MCP mogą wymagać aktualizacji:

# Sprawdź status serwera MCP
/mcp list

# Aby zaktualizować serwer MCP, usuń i dodaj ponownie
claude mcp remove <nazwa-serwera>
claude mcp add <nazwa-serwera> <komenda> [argumenty...]

Podsumowanie najlepszych praktyk

Zawsze twórz kopie zapasowe

Konfiguracji i niestandardowych komend przed każdą aktualizacją

Najpierw testuj

W izolowanym środowisku przed wdrożeniem zespołowym

Czytaj informacje o wydaniu

Zrozum zmiany i potencjalny wpływ

Koordynuj zespoły

Synchronizuj aktualizacje, aby uniknąć niezgodności wersji

Monitoruj po aktualizacji

Obserwuj zmiany wydajności lub nowe problemy

Dokumentuj wszystko

Prowadź dzienniki aktualizacji dla przyszłego odniesienia

Kontakty awaryjne

Jeśli podczas aktualizacji pojawią się krytyczne problemy:

1. GitHub Issues: Zgłaszaj błędy ze szczegółami wersji
2. Fora społeczności: Sprawdź, czy inni doświadczają tego samego problemu
3. Najpierw cofnij: Nie próbuj naprawiać do przodu w środowisku produkcyjnym
4. Dokumentuj dokładnie: Pomóż innym uniknąć tego samego problemu

Wskazówka

Pamiętaj: Szybki rozwój Claude Code oznacza częste aktualizacje z cennymi ulepszeniami. Dobrze zaplanowany proces aktualizacji pozwala czerpać korzyści z nowych funkcji przy jednoczesnym zachowaniu stabilności.