vite

Vite 运维

将此技能用于 Vite 工具链本身：项目发现、配置和插件行为、环境加载、开发服务器诊断、生产构建，以及资源和部署边界。应用架构和 UI 实现请交由 frontend-engineering，基础设施和 CI 设计请交由 platform-engineering，浏览器测试请交由 playwright，无障碍功能实现与审查请交由 web-accessibility。

操作约定

1. 先发现，再更改。 阅读 package.json、锁文件、vite.config.*、tsconfig*.json、脚本、框架插件和部署假设。根据锁文件确定包管理器；不要凭空编造命令。
2. 检查实际工具链。 从此技能目录或项目根目录运行 scripts/vite-doctor --json，以获取 Node、包管理器、Vite 包、配置和环境方面的证据。文档中提到的 Vite 版本不能证明当前安装的版本。
3. 保持配置明确。 检查 root、base、resolve.alias、插件、server.host/port、preview、build.outDir、build.rollupOptions 和 define。将 define 和 import.meta.env 视为编译时／公开数据；切勿将机密放入 VITE_* 变量或客户端包。
4. 构建后再宣称成功。 使用项目现有脚本（通常为 npm run build、pnpm build、yarn build 或 bun run build），并设置有界超时。检查输出文件和警告，然后尽可能在部署的基础路径下运行构建后的应用。
5. 将变更视为需审批操作。 可以进行只读发现。安装包、编辑配置、删除输出、启动服务器或更改部署设置之前，先确认目标、范围和回滚方式。优先使用新的输出目录或纳入版本控制的变更，绝不要覆盖用户尚未提交的工作。
6. 限制证据范围。 概述日志和错误；不要粘贴 .env 内容、令牌、完整包内容或生成的依赖树。

常见工作流

• 新建项目或迁移： 验证 Node 和包管理器，检查现有应用入口，选择框架插件，保留锁文件；仅当目标目录为空或已获明确批准时，才使用官方 Vite 脚手架。
• 配置变更： 尽量做最小更改，说明 base 和资源路径为何仍然正确，并运行生产构建。配置文件是可执行代码；不要将任意配置值加载到 define 中。
• 环境问题： 区分 .env、.env.local、特定模式文件和进程环境。默认情况下，只有带 VITE_ 前缀的变量会公开；更改后重启开发服务器。验证必需的值，但不要打印这些值。
• 开发服务器问题： 检查端口／主机／代理，以及请求是否同源。其他设备要访问服务器，可能需要显式指定主机并审查网络策略；不要随意将其暴露出去。
• 构建问题： 捕获第一个可采取行动的错误，检查插件与 Node/Vite 的兼容性，在获批后仅清除可复现的缓存，并重新运行导致问题的最小命令。不要试图通过大范围修改别名来掩盖模块解析失败。
• 部署问题： 确认 base、SPA 回退、静态资源缓存和托管平台的输出目录。构建成功并不能证明深层链接或客户端路由正常工作。

参考资料路由

加载时机	参考资料
配置、插件、模式、环境变量、别名或公共资源	references/config-and-environments.md
构建输出、依赖故障、性能或部署	references/build-and-deploy.md
开发服务器、代理、预览、诊断或安全操作	references/dev-server-and-diagnostics.md

验证边界

当所需的配置或构件已存在、相关命令成功退出，并且边界检查通过时，Vite 任务即告完成：构建任务检查构建输出，部署任务检查路由和资源是否可访问，E2E 声明则通过 playwright 检查浏览器中用户可见的行为。明确说明任何未经测试的浏览器、主机、模式或部署假设。

不适用场景

• 前端组件架构、状态、响应式 UI 或常规 Web 实现：frontend-engineering。
• 基础设施、CI 运行器、容器、托管拓扑或发布策略：platform-engineering。
• 编写或运行浏览器自动化：playwright。
• WCAG 审核、无障碍交互设计或语义无障碍修复：web-accessibility。
• Rollup 内部机制或迁移到非 Vite 打包器：使用相关工具或方法技能；对于现有 Vite 项目，仍可参考 Vite 特有行为。