npm run dev在Windows下卡于Compilation complete提示且未启动服务器求助

Hey there, let's work through this frustrating problem where your dev server gets stuck at "Compilation complete. Watching for file changes" on Windows but runs smoothly on Ubuntu. Here's a step-by-step breakdown to help you uncover hidden logs, identify the root cause, and fix it:

1. Force Detailed Debug Logs #

First, let's make your dev tool spit out more verbose output—often the critical error is hiding in silent logs.

• Open your package.json and tweak the dev script to add debug flags. Examples for common tools:
  • Vite: Change "dev": "vite" to "dev": "vite --debug"
  • Webpack: Change "dev": "webpack serve" to "dev": "webpack serve --progress --verbose"
  • Vue CLI: Use "dev": "vue-cli-service serve --verbose"
• Run npm run dev again. This should show you detailed runtime logs, including suppressed warnings or failed setup steps that weren't visible before.

2. Check for Port Conflicts #

Windows is notorious for having background apps hogging common dev ports (like 3000, 5173). Let's verify:

• Open Command Prompt or PowerShell and run:

  netstat -ano | findstr :<YOUR_DEV_PORT>
  

  Replace <YOUR_DEV_PORT> with your server's default port (usually 3000 for React/Vue, 5173 for Vite).
• If you see output with a PID number, another process is using that port. Open Task Manager, go to the "Details" tab, find the PID, and end that process.
• Alternatively, modify your project's config file to use a different port (e.g., in vite.config.js, set server.port: 3001).

3. Fix File System Watcher or Permission Issues #

Windows has stricter file system permissions and sometimes struggles with native file watchers:

• Run your terminal as Administrator: Right-click Command Prompt/PowerShell and select "Run as administrator", then try npm run dev again. This fixes permission-related blocks when the server tries to access or watch files.
• Move your project to a simple path: Windows can glitch with paths containing Chinese characters, spaces, or special symbols (like !, @). Move your project to something like C:\dev\my-project and test again.
• Force file polling (for Vite/Webpack): If the watcher isn't triggering correctly, enable polling. For Vite, add this to vite.config.js:

  export default {
    server: {
      watch: {
        usePolling: true
      }
    }
  }
  

  For Webpack, add watchOptions: { poll: 1000 } to your config.

4. Align Your Environment with Ubuntu #

Mismatched Node/npm versions or corrupted dependencies often cause OS-specific breaks:

• Check Node/npm versions: Run node -v and npm -v on both Windows and Ubuntu. If they're different, use nvm-windows to install the same Node version as your Ubuntu setup.
• Reinstall dependencies: Delete your node_modules folder and package-lock.json (or yarn.lock), then run npm install again. This ensures you get Windows-compatible builds of native dependencies (some packages compile differently per OS).

5. Run the Dev Command Directly #

Sometimes npm scripts suppress raw error messages. Skip the npm wrapper and run the underlying command directly:

• If your dev script is "vite", run vite in your terminal.
• If it's "vue-cli-service serve", run npx vue-cli-service serve.
• This will often reveal unfiltered error messages that npm was hiding.

6. Rule Out Firewall/Antivirus Interference #

Windows Defender or third-party antivirus might be blocking your dev server from starting or accessing files:

• Temporarily disable your firewall and antivirus software, then run npm run dev.
• If the server starts successfully, add your project folder and node.exe to the antivirus/firewall whitelist to prevent future blocks.

7. Check for Windows-Specific Config Issues #

Double-check your project config files for Linux-only settings:

• Ensure path separators are handled correctly (most modern tools auto-convert / to \ on Windows, but manual paths might cause issues).
• Look for any OS-specific conditional logic in config files (e.g., process.platform === 'linux' blocks that might skip critical setup for Windows).

Start with the first two steps (verbose logs and port checks)—they're the quickest to rule out common culprits. Let me know if you find any specific error messages!

内容的提问来源于stack exchange，提问作者Romain COMTET