知识库

Appearance

Return to top
On this page

Vite 开发服务器

Vite 的开发服务器是其核心功能之一，它利用现代浏览器的原生 ES 模块支持，提供了快速的冷启动和即时的热模块替换（HMR）功能。

启动开发服务器

启动开发服务器非常简单，只需运行：

bash
npm run dev

或者使用其他包管理器：

bash
# 使用 yarn
yarn dev

# 使用 pnpm
pnpm dev

服务器配置

端口配置

默认情况下，Vite 开发服务器运行在 http://localhost:5173。您可以通过配置更改端口：

javascript
// vite.config.js
export default {
  server: {
    port: 3000
  }
}

如果指定端口已被占用，Vite 会自动尝试下一个可用端口（如 3001、3002 等）。

主机配置

要使服务器可以被外部访问，可以配置主机：

javascript
// vite.config.js
export default {
  server: {
    host: '0.0.0.0' // 或使用 true
  }
}

自动打开浏览器

启动服务器时自动在浏览器中打开应用：

javascript
// vite.config.js
export default {
  server: {
    open: true
  }
}

您也可以指定打开的路径：

javascript
// vite.config.js
export default {
  server: {
    open: '/dashboard'
  }
}

代理配置

开发服务器内置了代理功能，用于解决开发环境中的跨域问题：

javascript
// vite.config.js
export default {
  server: {
    proxy: {
      // 字符串简写写法
      '/api': 'http://localhost:8080',
      
      // 详细配置
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      },
      
      // 使用数组配置多个目标
      '/api': {
        target: 'http://server1.com',
        ws: true,
        changeOrigin: true
      },
      
      // 复杂代理配置
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        configure: (proxy, options) => {
          // 自定义代理配置
          proxy.on('error', (err, req, res) => {
            console.log('代理错误:', err)
          })
        }
      }
    }
  }
}

WebSocket 代理

对于 WebSocket 连接，需要启用 ws 选项：

javascript
// vite.config.js
export default {
  server: {
    proxy: {
      '/socket.io': {
        target: 'http://localhost:8080',
        ws: true,
        changeOrigin: true
      }
    }
  }
}

热模块替换（HMR）

Vite 的热模块替换功能允许在不刷新整个页面的情况下更新模块，这大大提高了开发效率。

HMR API

在代码中使用 HMR API：

javascript
// 在客户端代码中
if (import.meta.hot) {
  // 接受自身更新
  import.meta.hot.accept((newModule) => {
    // 当模块自身更新时执行的回调
    console.log('模块已更新:', newModule)
  })

  // 接受依赖模块的更新
  import.meta.hot.accept('./dependency.js', (newDep) => {
    // 当依赖模块更新时执行的回调
  })

  // 拒绝更新（不接受父模块的更新）
  import.meta.hot.decline()

  // 模块卸载时的清理工作
  import.meta.hot.dispose(() => {
    // 清理代码
  })

  // 验证更新
  import.meta.hot.accept((newModule) => {
    if (!newModule.isVersionSupported) {
      import.meta.hot.invalidate() // 重新加载整个页面
    }
  })
}

Vue 中的 HMR

在 Vue 组件中，HMR 是自动处理的，无需额外配置：

vue
<template>
  <div>{{ message }}</div>
</template>

<script>
export default {
  data() {
    return {
      message: 'Hello Vite!'
    }
  }
}
</script>

React 中的 HMR

在 React 项目中，使用 Vite 的 React 插件会自动启用 Fast Refresh：

jsx
import React, { useState } from 'react'

function App() {
  const [count, setCount] = useState(0)

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>
        Increment
      </button>
    </div>
  )
}

export default App

中间件

Vite 开发服务器基于 Connect，支持添加自定义中间件：

javascript
// vite.config.js
export default {
  server: {
    middleware: [
      (req, res, next) => {
        // 自定义中间件逻辑
        console.log(`${req.method} ${req.url}`)
        next()
      }
    ]
  }
}

或者使用插件 API 添加中间件：

javascript
// vite.config.js
export default {
  plugins: [
    {
      name: 'custom-middleware',
      configureServer(server) {
        server.middlewares.use((req, res, next) => {
          // 自定义中间件
          console.log('Custom middleware:', req.url)
          next()
        })
      }
    }
  ]
}

SSL 配置

要启用 HTTPS，可以配置 SSL 选项：

javascript
// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    https: {
      key: fs.readFileSync(path.join(__dirname, 'cert/key.pem')),
      cert: fs.readFileSync(path.join(__dirname, 'cert/cert.pem'))
    }
  }
})

或者使用第三方工具如 mkcert 生成本地受信任的证书。

监视文件

Vite 会自动监视项目中的文件变化，但您也可以自定义监视选项：

javascript
// vite.config.js
export default {
  server: {
    watch: {
      // 忽略监视某些文件
      ignored: ['**/node_modules/**', '**/.git/**'],
      // 立即开始监视
      persistent: true
    }
  }
}

环境变量

开发服务器会自动加载 .env 文件中的环境变量：

  • .env：所有情况下都会加载
  • .env.local：本地覆盖，会被 git 忽略
  • .env.development：开发环境特定
  • .env.development.local：开发环境本地覆盖

环境变量使用前缀 VITE_：

text
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My App

在代码中使用：

javascript
console.log(import.meta.env.VITE_API_URL)

性能优化

依赖预构建

Vite 会自动预构建依赖，但您也可以自定义：

javascript
// vite.config.js
export default {
  optimizeDeps: {
    include: ['vue', 'vue-router'],
    exclude: ['some-big-lib'],
    force: true // 强制预构建
  }
}

文件监听优化

对于大型项目，可以优化文件监听：

javascript
// vite.config.js
export default {
  server: {
    watch: {
      usePolling: true, // 使用轮询（某些网络文件系统需要）
      interval: 1000   // 轮询间隔
    }
  }
}

常见问题

端口被占用

如果默认端口 5173 被占用，Vite 会自动尝试下一个端口。您也可以手动指定：

bash
npm run dev -- --port 3000

网络访问问题

如果外部无法访问开发服务器，请检查：

  1. server.host 是否设置为 0.0.0.0 或 true
  2. 防火墙设置
  3. 网络配置

HMR 不工作

如果 HMR 不起作用，请检查：

  1. 模块是否正确导出
  2. 是否在支持的框架中使用
  3. 控制台是否有错误信息

Vite 的开发服务器提供了现代化的开发体验，通过快速启动、即时反馈和丰富的配置选项，极大地提升了前端开发效率。