debug_svelte（调试 Svelte）

Svelte Debugging Guide

This guide provides a systematic approach to debugging Svelte applications, with special emphasis on Svelte 5 runes and reactivity patterns.

Common Error Patterns

1. Reactivity Not Triggering

Symptoms:

• UI doesn't update when state changes
• Computed values are stale
• Event handlers seem to fire but nothing happens

Root Causes:

<!-- WRONG: Mutating object properties without reassignment (Svelte 4) -->
<script>
  let user = { name: 'John' };
  function updateName() {
    user.name = 'Jane';  // Won't trigger reactivity in some cases
  }
</script>

<!-- CORRECT: Reassign the entire object -->
<script>
  let user = { name: 'John' };
  function updateName() {
    user = { ...user, name: 'Jane' };  // Triggers reactivity
  }
</script>

Svelte 5 Fix with Runes:

<script>
  let user = $state({ name: 'John' });
  function updateName() {
    user.name = 'Jane';  // Deep reactivity works with $state
  }
</script>

2. Runes ($state, $derived, $effect) Issues

Error: "Cannot use runes in.js files"

# WRONG: Using runes in regular JS file
# utils.js
export const count = $state(0);  // ERROR!

# CORRECT: Rename to .svelte.js
# utils.svelte.js
export const count = $state(0);  // Works!

Error: "Class properties not reactive"

// WRONG: $state wrapper on class instance has no effect
let instance = $state(new MyClass());  // Properties NOT reactive

// CORRECT: Make class properties reactive internally
class MyClass {
  count = $state(0);
  name = $state('');
}
let instance = new MyClass();  // Properties ARE reactive

Error: "Infinite loop in $derived"

<script>
  let count = $state(0);

  // WRONG: Modifying state inside $derived
  let doubled = $derived(() => {
    count++;  // ERROR: Causes infinite loop!
    return count * 2;
  });

  // CORRECT: Pure computation only
  let doubled = $derived(count * 2);
</script>

Error: "Infinite update loop in $effect"

<script>
  import { untrack } from 'svelte';

  let count = $state(0);
  let log = $state([]);

  // WRONG: Reading and writing same state
  $effect(() => {
    log.push(count);  // Infinite loop!
  });

  // CORRECT: Use untrack() to break dependency
  $effect(() => {
    untrack(() => {
      log.push(count);
    });
  });
</script>

Error: "Cannot export reassigned $state"

// WRONG: Exporting reassigned state
// store.svelte.js
export let count = $state(0);  // ERROR if reassigned

// CORRECT: Wrap in object for mutation
export const state = $state({ count: 0 });
// Or use getter/setter
let _count = $state(0);
export const count = {
  get value() { return _count; },
  set value(v) { _count = v; }
};

3. Store Subscription Problems (Svelte 4)

Memory Leak: Forgotten Unsubscribe

<script>
  import { myStore } from './stores';
  import { onDestroy } from 'svelte';

  // WRONG: No cleanup
  myStore.subscribe(value => console.log(value));

  // CORRECT: Clean up subscription
  const unsubscribe = myStore.subscribe(value => console.log(value));
  onDestroy(unsubscribe);

  // BEST: Use auto-subscription
  $: value = $myStore;  // Svelte handles cleanup
</script>

Store Not Updating

// WRONG: Mutating store value
import { writable } from 'svelte/store';
const items = writable([]);
items.update(arr => {
  arr.push('new item');  // Mutation, may not trigger
  return arr;
});

// CORRECT: Return new array
items.update(arr => [...arr, 'new item']);

4. SSR Hydration Mismatches

Symptoms:

• Console warning about hydration mismatch
• Content flickers on page load
• Interactive elements don't work initially

Common Causes:

<script>
  import { browser } from '$app/environment';

  // WRONG: Different content server vs client
  let date = new Date().toLocaleString();  // Different on each render!

  // CORRECT: Initialize consistently, update on mount
  let date = '';
  import { onMount } from 'svelte';
  onMount(() => {
    date = new Date().toLocaleString();
  });

  // OR: Guard browser-only code
  {#if browser}
    <BrowserOnlyComponent />
  {/if}
</script>

LocalStorage Access

<script>
  import { browser } from '$app/environment';

  // WRONG: Accessing localStorage during SSR
  let theme = localStorage.getItem('theme');  // ERROR on server!

  // CORRECT: Guard with browser check
  let theme = $state('light');
  if (browser) {
    theme = localStorage.getItem('theme') ?? 'light';
  }
</script>

5. Compiler Errors

"'foo' is not defined"

<!-- Check for typos in variable names -->
<!-- Check script context vs module context -->
<script context="module">
  // This runs once, not per component
  export const sharedValue = 'shared';
</script>

<script>
  // This runs per component instance
  let instanceValue = 'instance';
</script>

"Cannot bind to property"

<script>
  // WRONG: Binding to non-bindable prop
  let { value } = $props();
</script>
<input bind:value />  <!-- Error if parent doesn't use bind: -->

<!-- CORRECT: Declare as bindable -->
<script>
  let { value = $bindable() } = $props();
</script>

Debugging Tools

1. Svelte DevTools Browser Extension

Install from Chrome Web Store or Firefox Add-ons. Provides:

• Component tree visualization
• Props and state inspection
• Store value monitoring
• Event tracking

2. The $inspect() Rune (Svelte 5)

<script>
  let count = $state(0);
  let user = $state({ name: 'John' });

  // Log when values change
  $inspect(count);  // Logs: "count", 0, then changes

  // Custom effect with .with()
  $inspect(user).with(console.trace);  // Show stack trace

  // Multiple values
  $inspect(count, user);
</script>

3. The {@debug} Tag

<script>
  let items = ['a', 'b', 'c'];
  let filter = '';
</script>

<!-- Pauses execution with devtools open -->
{@debug items, filter}

<!-- Shows in console when values change -->
{#each items as item}
  {@debug item}
  <li>{item}</li>
{/each}

4. Console Methods

<script>
  import { onMount, beforeUpdate, afterUpdate, onDestroy } from 'svelte';

  // Track component lifecycle
  onMount(() => console.log('Component mounted'));
  beforeUpdate(() => console.log('Before update'));
  afterUpdate(() => console.log('After update'));
  onDestroy(() => console.log('Component destroyed'));

  // Reactive statement debugging
  $: console.log('Count changed:', count);

  // Object inspection
  $: console.table(items);
  $: console.dir(complexObject, { depth: null });
</script>

5. Vite Dev Server

# Start with verbose logging
npm run dev -- --debug

# Clear cache if issues persist
rm -rf node_modules/.vite
npm run dev

6. svelte-check CLI

# Type checking and diagnostics
npx svelte-check

# Watch mode
npx svelte-check --watch

# With specific tsconfig
npx svelte-check --tsconfig ./tsconfig.json

# Output format for CI
npx svelte-check --output human-verbose

7. VS Code Debugging

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Debug Svelte",
      "url": "http://localhost:5173",
      "webRoot": "${workspaceFolder}",
      "sourceMaps": true
    }
  ]
}

Enable breakpoints in.svelte files:

1. Open VS Code settings
2. Search for debug.allowBreakpointsEverywhere
3. Enable the setting

The Four Phases (Svelte-specific)

Phase 1: Gather Information

# Check Svelte version
npm list svelte

# Check for type errors
npx svelte-check --output human-verbose

# Check browser console for warnings/errors
# Look for:
# - Hydration warnings
# - Reactivity warnings
# - Unhandled promise rejections

# Check component props
$inspect($$props);  # Svelte 5

Questions to Answer:

• Is this a Svelte 4 or Svelte 5 project?
• Are you using SvelteKit or standalone Svelte?
• Does the issue occur in dev, build, or both?
• Is it SSR-related (works in CSR but not SSR)?

Phase 2: Isolate the Problem

<!-- Create minimal reproduction -->
<script>
  // Strip component to minimum code that reproduces issue
  let count = $state(0);

  // Add debugging
  $inspect(count);

  function handleClick() {
    console.log('Before:', count);
    count++;
    console.log('After:', count);
  }
</script>

<button onclick={handleClick}>
  Count: {count}
</button>

Isolation Strategies:

1. Comment out unrelated code
2. Remove external dependencies
3. Test in fresh component
4. Check if issue is component-specific or global

Phase 3: Form Hypothesis and Test

Common Hypotheses:

<script>
  // Hypothesis: Props not updating
  // Test 1: Log prop changes
  let { value } = $props();
  $effect(() => {
    console.log('Prop value changed:', value);
  });

  // Test 2: Check if parent is reactive
  // Add $inspect in parent component
</script>

Phase 4: Fix and Verify

Verification Checklist:

• Issue no longer occurs
• No new console warnings
• svelte-check passes
• Works in both dev and build
• Works in SSR (if applicable)
• No memory leaks (check DevTools)

# Full verification
npx svelte-check
npm run build
npm run preview  # Test production build

Quick Reference Commands

Diagnostic Commands

# Check Svelte/SvelteKit versions
npm list svelte @sveltejs/kit

# Run type checking
npx svelte-check

# Run type checking with watch
npx svelte-check --watch

# Check for outdated packages
npm outdated

# Clear caches
rm -rf node_modules/.vite .svelte-kit
npm run dev

Common Fixes

# Reset node_modules
rm -rf node_modules package-lock.json
npm install

# Regenerate SvelteKit types
npx svelte-kit sync

# Update Svelte to latest
npm update svelte @sveltejs/kit

# Check for peer dependency issues
npm ls

Debug Environment Variables

# Enable Vite debug mode
DEBUG=vite:* npm run dev

# Enable SvelteKit debug mode
DEBUG=kit:* npm run dev

# Both
DEBUG=vite:*,kit:* npm run dev

Svelte 5 Migration Pitfalls

From let to $state

<!-- Svelte 4 -->
<script>
  let count = 0;  // Implicitly reactive at top level
</script>

<!-- Svelte 5 -->
<script>
  let count = $state(0);  // Explicitly reactive
</script>

From $: to $derived/$effect

<!-- Svelte 4 -->
<script>
  $: doubled = count * 2;  // Reactive derivation
  $: console.log(count);   // Reactive side effect
</script>

<!-- Svelte 5 -->
<script>
  let doubled = $derived(count * 2);  // Derivation
  $effect(() => {
    console.log(count);  // Side effect
  });
</script>

From export let to $props

<!-- Svelte 4 -->
<script>
  export let name = 'default';
  export let value;
</script>

<!-- Svelte 5 -->
<script>
  let { name = 'default', value } = $props();
</script>

From createEventDispatcher to Callback Props

<!-- Svelte 4 -->
<script>
  import { createEventDispatcher } from 'svelte';
  const dispatch = createEventDispatcher();
  function handleClick() {
    dispatch('click', { data: 'value' });
  }
</script>

<!-- Svelte 5 -->
<script>
  let { onclick } = $props();
  function handleClick() {
    onclick?.({ data: 'value' });
  }
</script>

Reactive Collections (Svelte 5)

// Import reactive versions of Map, Set, etc.
import { SvelteMap, SvelteSet, SvelteURL } from 'svelte/reactivity';

// Use instead of native collections
let items = new SvelteMap();
let tags = new SvelteSet();

// These are deeply reactive
items.set('key', { nested: 'value' });
tags.add('new-tag');

Form Handling with tick()

<script>
  import { tick } from 'svelte';

  let value = $state('');

  async function submitWithValue(newValue) {
    value = newValue;
    await tick();  // Wait for DOM to update
    form.submit();  // Now form has updated value
  }
</script>

Sources

• Svelte @debug Documentation
• SvelteKit Breakpoint Debugging
• Svelte 5 Migration Guide
• Svelte 5 States: Avoiding Common Reactivity Traps
• The Guide to Svelte Runes
• Introducing Runes
• Exploring the Magic of Runes in Svelte 5