Vite 核心使用指南

创建与运行

快速启动一个新的 Vite 项目。

  1. 创建项目: 运行 npm create vite@latest 并按提示操作。
  2. 初始化项目: 进入项目目录 cd project-name，然后运行 npm install 安装依赖。
  3. 启动开发服务器: 运行 npm run dev，享受极速热更新开发体验。

依赖管理

理解和管理项目的运行时依赖与开发依赖。

  • 运行时依赖 (dependencies): 应用实际运行时必需的库 (如 Three.js, React)。使用 npm install <包名> 安装。
  • 开发依赖 (devDependencies): 仅在开发和构建过程中使用的工具 (如 Vite, ESLint)。使用 npm install -D <包名> 安装。
  • 安装所有依赖: 运行 npm install 会根据 package.json 和 package-lock.json 安装。
  • 重要: 务必将 package-lock.json 文件提交到版本控制系统 (如 Git)，它能锁定依赖版本，确保团队成员和部署环境安装完全一致的依赖。
  • 代码中使用: 使用 ES Module 语法 import ... from '包名'; 引入依赖。

构建、预览与部署

将项目打包为生产环境的静态文件，并进行预览和部署。

  • 构建: 运行 npm run build。Vite 会优化代码并输出静态文件到 dist 目录。
  • 本地预览: 构建完成后，运行 npm run preview。它会启动一个本地服务器来模拟生产环境，访问提示的 URL 进行测试。
  • 禁止操作: **不要**直接在文件浏览器中双击打开 dist/index.html 文件进行测试，这会导致资源加载失败或功能异常，必须通过 HTTP 服务器访问。
  • 部署: 将 dist 目录的**全部内容**上传到你的 Web 服务器或静态托管平台 (如 Netlify, Vercel, GitHub Pages)。
  • 单页应用 (SPA) 路由: 如果你的应用使用了前端路由（非 Hash 模式），确保服务器配置能将所有不存在的路径请求都指向 index.html，以便前端路由接管。
  • 子目录部署: 如果项目部署在服务器的子目录下 (例如 /my-app/)，你需要在 vite.config.js 中配置 base: '/my-app/'，然后**重新构建**项目。

配置文件 (vite.config.js)

自定义 Vite 的行为，如添加插件、设置别名等。

  • 可选文件: 该文件是可选的。只有当你需要修改 Vite 的默认设置或添加插件时，才需要在项目根目录**手动创建**它。
  • 覆盖机制: vite.config.js 中**只覆盖**你明确指定的配置项。所有未在文件中设置的选项，Vite **仍会使用其默认值**。
  • 默认路径规则:
    • Vite 默认视项目根目录（包含 index.html, src 的地方）为 Web 服务器的根目录。
    • 请求一个路径时 (如 /logo.png 或 /src/main.js)，Vite 会**优先**在项目根目录查找。
    • 如果在根目录找不到，Vite 会**接着**去项目根目录下的 public 文件夹里查找同名文件。

构建用于本地直接打开 (file:///)

配置 Vite 使构建后的 index.html 文件可以不通过服务器，直接在浏览器中打开（但有严重限制）。

方法一：相对路径 (推荐)

  1. 配置: 手动创建或修改 vite.config.js，设置 base 选项为 './'。 
    // vite.config.js
import { defineConfig } from 'vite';
export default defineConfig({ base: './' });
  2. 构建: 运行 npm run build。
  3. 结果: dist/index.html 中的资源引用将使用相对路径 (如 ./assets/index-....js)。

方法二：内联为单文件

  1. 安装插件: 运行 npm install -D vite-plugin-singlefile。
  2. 配置: 手动创建或修改 vite.config.js，导入并使用该插件。 
    // vite.config.js
import { defineConfig } from 'vite';
import { viteSingleFile } from 'vite-plugin-singlefile';

export default defineConfig({
  plugins: [viteSingleFile()],
  // 使用此插件时通常不需要设置 base
});
  3. 构建: 运行 npm run build。
  4. 结果: 生成的 dist/index.html 将包含所有内联的 JS 和 CSS，成为一个独立的（可能很大的）HTML 文件。

严重警告：file:/// 协议的限制

直接使用 file:/// 协议打开网页存在**重大限制**，可能导致功能失效：

  • 网络请求 (如 fetch, XHR) 会因 CORS 策略而失败。
  • 本地存储 (LocalStorage)、Service Workers、Web Workers 等 API 可能受限或无法工作。
  • 依赖服务器重定向的前端路由模式 (History Mode) 无法使用。

**此方法仅适用于非常简单的、无网络交互、不依赖特定浏览器 API 的离线展示或特定打包场景。常规测试和部署请务必使用 HTTP 服务器。**