Bezpieczne procedury aktualizacji

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

Zrozumienie ścieżek aktualizacji

Auto-aktualizacje (domyślne)

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

Ręczne aktualizacje

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

Przypinanie wersji

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

Gotowość do cofnięcia

Zawsze zachowuj możliwość przywrócenia - krytyczne dla środowisk produkcyjnych

Lista kontrolna przed aktualizacją

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

1. Sprawdź obecną wersję

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

2. Przejrzyj informacje o wydaniu

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

3. Kopia zapasowa krytycznych konfiguracji

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

4. Testuj w niekrytycznym środowisku

   • Najpierw użyj projektu piaskownicy
   • Zweryfikuj, że podstawowe przepływy pracy nadal działają
   • Sprawdź niestandardowe polecenia i hooki

5. Powiadom członków zespołu

   • Komunikuj harmonogram aktualizacji
   • Udostępnij wszelkie zmiany przełomowe
   • Koordynuj czas dla minimalnych zakłóceń

Procedury aktualizacji według typu instalacji

Globalna instalacja NPM

Standardowa aktualizacja

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

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

# Zweryfikuj aktualizację
claude --version

Czysta instalacja

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

Konkretna wersja

# Przypnij do konkretnej 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 migrate-installer

Instalacja lokalna (zalecana)

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

# Jeśli jeszcze nie migrowałeś
claude migrate-installer

# Aktualizacje odbywają się automatycznie lub ręcznie
claude update

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

Natywna instalacja binarna (Alpha)

Aktualizuj plik binarny

# Z istniejącej instalacji
claude install

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

Uwagi platformowe

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

Obsługa zmian przełomowych

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

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

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-4.1-opus-20240229-v1:0"
   # Uwaga: Bez %2F, użyj literalnego /

3. Przetestuj konfigurację

   # Zweryfikuj, że konfiguracja działa
   claude doctor

4. Kontynuuj aktualizację

   claude update

Typowe kategorie zmian przełomowych

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 poleceń

Polecenia slash lub flagi zmodyfikowane lub przestarzałe

Strategia aktualizacji dla przedsiębiorstw

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 stopniowego wdrażania

1. Środowisko deweloperskie

   • Testuj z programistami-ochotnikami
   • Uruchom na 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
   • Rozłożone według zespołu/regionu
   • Monitoruj problemy

4. Przegląd po aktualizacji

   • Zbierz opinie zespołu
   • Udokumentuj wszelkie problemy
   • Zaktualizuj procedury

Zarządzanie konfiguracją przedsiębiorstwa

# 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 wdrożenia
#!/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 cofania

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 zachowują 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 cofania

• Zatrzymaj wszystkie działające instancje Claude Code
• Przywróć poprzednią wersję
• Przywróć kopie zapasowe konfiguracji
• Wyczyść wszelką uszkodzoną pamięć podręczną/stan
• Zweryfikuj funkcjonalność
• Udokumentuj problemy do raportu błędu

Weryfikacja po aktualizacji

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

1. Podstawowa funkcjonalność

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

2. Integralność konfiguracji

   # Zweryfikuj zachowane ustawienia
   claude config get autoUpdates --global
   claude config get model --global
   
   # Sprawdź niestandardowe polecenia
   ls .claude/commands/

3. Funkcjonalność narzędzi

   # Testuj operacje na plikach
   claude "Wyświetl pliki w bieżącym katalogu"
   
   # Testuj 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, uszkodzenie konfiguracji jest często przyczyną.

# Zdiagnozuj problemy z konfiguracją
claude doctor

# Zresetuj do domyślnych jeśli potrzeba
mv ~/.claude/config.json ~/.claude/config.json.backup
claude # Odtworzy z 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 migrate-installer

Konflikty wersji

# Sprawdź wiele instalacji
which -a claude
type -a claude

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

Zgodność serwerów MCP

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

# Sprawdź status serwera MCP
/mcp list

# Zaktualizuj konfiguracje MCP jeśli potrzeba
claude mcp update <nazwa-serwera>

Podsumowanie najlepszych praktyk

Zawsze kopia zapasowa

Konfiguracja i niestandardowe polecenia przed każdą aktualizacją

Najpierw testuj

W izolowanym środowisku przed wdrożeniem w całym zespole

Czytaj informacje o wydaniu

Zrozum zmiany i potencjalne wpływy

Koordynuj zespoły

Synchronizuj aktualizacje, aby uniknąć niedopasowań wersji

Monitoruj po aktualizacji

Obserwuj zmiany wydajności lub nowe problemy

Dokumentuj wszystko

Prowadź dzienniki aktualizacji do przyszłego odniesienia

Kontakty awaryjne

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

1. Zgłoszenia GitHub: Zgłoś 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 produkcji
4. Dokładnie udokumentuj: 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 korzystać z nowych funkcji przy zachowaniu stabilności.