So beheben Sie den Fehler „Eigenschaften von undefiniert können nicht gelesen werden“ in JavaScript

TypeError: Cannot read properties of undefined (reading 'x')ist der häufigste Laufzeitfehler in JavaScript. Die Botschaft ist präzise, wenn man erst einmal gelernt hat, sie zu lesen, und die Lösung ist fast immer eines von fünf Mustern. In diesem Leitfaden erfahren Sie, wie Sie die Ursache schnell lokalisieren und ein erneutes Auftreten verhindern können.

Was der Fehler tatsächlich bedeutet

Sie haben versucht, eine Eigenschaft von etwas zu lesen, dasundefinedist . Der Teil in Klammern gibt an, welche Eigenschaft Sie zu lesen versucht haben.

const user = undefined;
console.log(user.name);
// TypeError: Cannot read properties of undefined (reading 'name')

Die kritische Erkenntnis:Das Problem ist nicht die Eigenschaft, sondern die Sache vor dem Punkt. Wenn Sie(reading 'name')sehen , der Fehler besteht darin, dass das, was das Benutzerobjekt hätte enthalten sollen,undefinedist . Jeder verliert Zeit beim Debuggenname wenn sie fragen sollten, warumuser ist leer.

Arbeiten Sie in einer Kette von links nach rechts, um das erste undefinierte Glied zu finden.

const response = { data: { items: [] } };
console.log(response.data.results.length);
// TypeError: Cannot read properties of undefined (reading 'length')
// 'results' does not exist on data, so response.data.results is undefined.

Ursache 1: Asynchrone Daten werden gelesen, bevor sie eintreffen

Bei realen Anwendungen die mit Abstand häufigste Ursache. Der Status beginnt leer, das Rendern wird ausgeführt und der Abruf wurde noch nicht aufgelöst.

function Profile({ userId }) {
  const [user, setUser] = useState();   // undefined on first render

  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then(r => r.json())
      .then(setUser);
  }, [userId]);

  return <h1>{user.name}</h1>;   // throws on the very first render
}

Behebung durch Initialisierung auf einen sinnvollen leeren Wert und Überwachung des Renderings.

function Profile({ userId }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    let cancelled = false;
    setLoading(true);

    fetch(`/api/users/${userId}`)
      .then(r => {
        if (!r.ok) throw new Error(`HTTP ${r.status}`);
        return r.json();
      })
      .then(data => { if (!cancelled) setUser(data); })
      .catch(err => { if (!cancelled) console.error(err); })
      .finally(() => { if (!cancelled) setLoading(false); });

    return () => { cancelled = true; };
  }, [userId]);

  if (loading) return <p>Loading…</p>;
  if (!user)   return <p>User not found.</p>;

  return <h1>{user.name}</h1>;
}

Dascancelled Flag verhindert auch einen zweiten häufigen Fehler: eine langsame Antwort von einem vorherigenuserId Überschreiben neuerer Daten, nachdem sich die Requisite geändert hat.

Ursache 2: Die API-Antwortform entspricht nicht Ihren Annahmen

Du hastdata.itemsgeschrieben aber die API gibt{ results: [...] }zurück , oder es verpackt alles in{ data: { ... } }. Dies kann besonders leicht bei Axios passieren, das sein eigenesdatahinzufügt Wrapper über dem Antworttext.

// Axios puts the response body in .data — so the payload is often data.data
const response = await axios.get('/api/users');
console.log(response.data.users);     // correct
console.log(response.users);          // undefined -> throws downstream

Protokollieren Sie die gesamte Antwort, bevor Sie sie indizieren. Einconsole.log(JSON.stringify(response, null, 2)) beantwortet die Frage sofort, wohingegen Raten dies nicht tut.

Ursache 3: Array-Suchmethoden, die nichts gefunden haben

find gibtundefinedzurück wenn kein Element übereinstimmt, und dies ist die häufigste Fehlerquelle im Listenverarbeitungscode.

const users = [{ id: 1, name: 'Ada' }];
const match = users.find(u => u.id === 99);
console.log(match.name);
// TypeError: Cannot read properties of undefined (reading 'name')

Behandeln Sie das Ergebnis immer als möglicherweise fehlend.

const match = users.find(u => u.id === 99);
if (!match) {
  return null;               // or throw a clear domain error
}
console.log(match.name);

// Or with optional chaining when a missing value is acceptable:
console.log(match?.name ?? 'Unknown user');

Das Gleiche gilt fürdocument.querySelector, wasnullzurückgibt wenn nichts übereinstimmt, und zuMap.get undArray.at.

Ursache 4: Destrukturierung eines undefinierten Objekts

Durch die Destrukturierung werden Eigenschaften gelesen und daher aus genau demselben Grund ausgelöst – nur mit einer weniger offensichtlichen Stapelzeile.

function greet({ name }) {
  return `Hello ${name}`;
}
greet();
// TypeError: Cannot destructure property 'name' of 'undefined'

Geben Sie dem Parameter einen Standardwert, damit die Destruktur immer über ein Objekt verfügt, mit dem sie arbeiten kann.

function greet({ name = 'friend' } = {}) {
  return `Hello ${name}`;
}
greet();               // "Hello friend"
greet({ name: 'Ada' }); // "Hello Ada"

Ursache 5:this Hat seine Bindung verloren

Wenn eine Methode als Rückruf übergeben wird,this ist nicht mehr das Objekt, daher schlägt jede darauf gelesene Eigenschaft fehl.

class Counter {
  constructor() { this.count = 0; }
  increment() { this.count++; }   // 'this' is undefined when detached
}

const c = new Counter();
button.addEventListener('click', c.increment);
// TypeError: Cannot read properties of undefined (reading 'count')

Binden Sie es oder verwenden Sie ein Klassenfeld mit einer Pfeilfunktion, diethiserfasst lexikalisch.

class Counter {
  count = 0;
  increment = () => { this.count++; };   // arrow field — always bound
}

const c = new Counter();
button.addEventListener('click', c.increment);   // works

Die Tools, die es verhindern

Optionale Verkettung Kurzschlüsse nachundefined statt zu werfen.

const city = user?.address?.city;              // undefined, no throw
const first = users?.[0]?.name;                // works on arrays too
const result = api.getUser?.(id);              // and on possibly-missing methods

Nullhaftes Zusammenwachsen Bietet nur einen Fallback fürnull undundefined, im Gegensatz zu|| was auch0ersetzt und leere Zeichenfolgen.

const count = data?.count ?? 0;      // 0 stays 0
const wrong = data?.count || 0;      // a real 0 becomes 0 anyway, but '' becomes 0 too

Verwenden Sie eine optionale Verkettung, wenn ein fehlender Wert tatsächlich gültig ist. Verteilen Sie es nicht überall, um Fehler zum Schweigen zu bringen – wennuser Sollte zu diesem Zeitpunkt immer vorhanden sein, verwandelt das Verstecken seiner Abwesenheit einen lauten Fehler in einen stillen, der später ohne Stapelverfolgung auftaucht.

Debugging-Methode

Wenn der Fehler auftritt, führen Sie diese Reihenfolge durch.

1. Lesen Sie den Eigenschaftsnamen in Klammern. Der Fehler liegt im Ausdruckvor diese Eigenschaft.
2. Öffnen Sie den Stack-Trace und klicken Sie auf den obersten Frame in Ihrem eigenen Code. Bibliotheksframes werden dabei ignoriert.
3. Setzen Sie einen Haltepunkt in dieser Zeile und prüfen Sie den enthaltenden Ausdruck, nicht die Eigenschaft.
4. Gehen Sie die Kette von links nach rechts entlang, um das erste undefinierte Glied zu finden.
5. Fragen Sie, warum dieser Wert leer ist – wurde ein Abruf nicht aufgelöst, ist eine Suche fehlgeschlagen, wurde eine Requisite nie übergeben?

In der Produktion sind Quellkarten unerlässlich. Ohne sie weist der Trace auf minimierten Code hin und dieser Prozess ist unmöglich.

Strukturell verhindern

TypeScript fängt die meisten davon zur Kompilierzeit ab, insbesondere mitstrictNullChecks ermöglicht. Es zwingt Sie, den undefinierten Fall zu behandeln, bevor der Code ausgeführt wird.

function getName(user: User | undefined): string {
  // Error: 'user' is possibly 'undefined' — caught before runtime
  return user.name;
}

An Grenzen validieren. Analysieren Sie API-Antworten mit einem Schema-Validator wie Zod, sodass eine unerwartete Form sofort mit einer klaren Nachricht fehlschlägt, anstatt undefinierte drei Ebenen in Ihren Rendering-Code zu übertragen.

Gibt leere Sammlungen zurück, nicht undefiniert. Eine Funktion, die[]zurückgibt stattundefined ermöglicht es Anrufern, das Ergebnis bedingungslos zuzuordnen.

Häufig gestellte Fragen

F: Was ist der Unterschied zwischen diesem und „Eigenschaften von Null können nicht gelesen werden“?
A: Nur der Wert. undefined bedeutet normalerweise, dass eine Variable nie zugewiesen wurde oder eine Eigenschaft nicht existiert; null bedeutet normalerweise, dass etwas es explizit auf leer gesetzt hat. Der Debugging-Ansatz ist identisch.

F: Sollte ich einfach überall eine optionale Verkettung hinzufügen?
A: Nein. Verwenden Sie es, wenn ein Wert legitimerweise optional ist. Wenn Sie damit einen Fehler unterdrücken, den Sie nicht verstehen, wird ein Absturz mit einem Stack-Trace in ein falsches Verhalten ohne Trace umgewandelt.

F: Warum funktioniert es lokal, schlägt aber in der Produktion fehl?
A: Normalerweise Timing oder Daten. Lokale APIs reagieren schneller, sodass Race Conditions ausgeblendet werden. und Produktionsdaten enthalten Formen, die Ihre Testdaten nicht haben, z. B. Datensätze mit fehlenden optionalen Feldern.

F: Wie finde ich den Fehler, wenn im Stacktrace nur Bibliothekscode angezeigt wird?
A: Aktivieren Sie Quellzuordnungen und verwenden Sie dann die „Ignorierungsliste“ in den Chrome DevTools, um Framework-Frames auszublenden, sodass der oberste sichtbare Frame Ihr eigener Code ist.

F: Beseitigt TypeScript diesen Fehler vollständig?
A: Nein. Es eliminiert es für Code, den es überprüfen kann, aber Daten, die Laufzeitgrenzen überschreiten – API-Antworten, JSON-Analyse,any casts – können zur Laufzeit immer noch undefiniert sein. Validieren Sie externe Daten sogar in TypeScript.

Fazit

FixierungCannot read properties of undefined ist mechanisch, wenn man die Regel kennt:Der Fehler liegt im Ausdruck vor der Eigenschaft, nicht in der Eigenschaft selbst. Überprüfen Sie die fünf üblichen Ursachen – asynchrone Daten, die zu früh gelesen wurden, eine nicht übereinstimmende API-Form, einfind das passte zu nichts, zerstörte ein abwesendes Objekt und ein verlorenesthis Bindung. Verhindern Sie dann eine Wiederholung mit optionaler Verkettung, bei der Werte wirklich optional sind, TypeScript mitstrictNullChecksund Schemavalidierung an jeder Grenze, an der externe Daten in Ihr System gelangen.