前端工程化 / 系统课时

确认配置是否生效

确认配置是否生效

本课解决“配置明明写了却没有效果”的定位问题。你将用工作目录、显式配置路径、配置标记和最终解析结果建立证据链,判断是文件未加载、条件分支未命中,还是配置被命令行或插件改写。

学习目标

  • 确认 Vite 实际使用的工作目录与配置文件
  • 输出并核对最终解析后的关键配置
  • 区分配置未加载、分支未命中和选项被覆盖

先固定运行入口

Vite 默认在项目根目录中查找 vite.config.js 及受支持的 JS、TS 变体;使用 --config 时,配置文件路径相对于当前工作目录解析。因此,排查第一步不是修改选项,而是确认命令究竟从哪里启动。:contentReference[oaicite:0]{index=0}

bash
pwd
node -p "process.cwd()"

预期输出

text
<PATH>
<PATH>

两行应指向同一个预期项目目录。若不同,先检查终端所在目录、工作区任务、容器挂载路径或 monorepo 脚本的启动位置;<PATH> 会随机器而变化。

为配置加入唯一标记

新建 configs/vite.verify.ts。示例只保留少量关键选项,并通过 configResolved 输出最终配置;该钩子在配置解析完成后执行,适合观察最终生效值。:contentReference[oaicite:1]{index=1}

ts
import { defineConfig } from 'vite'

const marker = 'vite-config-verify-08-01'

export default defineConfig(({ command, mode }) => ({
  base: '/verify/',
  server: {
    port: 4173,
    strictPort: true,
  },
  define: {
    __CONFIG_MARKER__: JSON.stringify(marker),
  },
  plugins: [
    {
      name: 'print-resolved-config',
      configResolved(config) {
        // 只输出足以定位加载文件和覆盖来源的字段
        console.log(
          '[config-check]',
          JSON.stringify(
            {
              marker,
              cwd: process.cwd(),
              root: config.root,
              configFile: config.configFile,
              command,
              resolvedCommand: config.command,
              mode,
              resolvedMode: config.mode,
              base: config.base,
              port: config.server.port,
            },
            null,
            2,
          ),
        )
      },
    },
  ],
}))

这段配置的生效行为是:开发服务器使用 /verify/ 作为基础路径并尝试监听 4173;终端同时打印配置文件、根目录、命令、模式和最终端口。define 中的标记还可供应用代码做临时验证,排查完成后应删除。

显式启动并读取结果

使用显式配置文件、固定模式和调试日志启动。Vite CLI 支持 --config、--mode、--debug 与 --clearScreen,显式参数可避免默认发现过程掩盖问题。:contentReference[oaicite:2]{index=2}

bash
npm exec vite -- --config ./configs/vite.verify.ts --mode verify --debug --clearScreen false

预期输出中的关键片段

text
[config-check] {
  "marker": "vite-config-verify-08-01",
  "cwd": "<PATH>",
  "root": "<PATH>",
  "configFile": "<PATH>/configs/vite.verify.ts",
  "command": "serve",
  "resolvedCommand": "serve",
  "mode": "verify",
  "resolvedMode": "verify",
  "base": "/verify/",
  "port": 4173
}

调试日志和启动地址可能因版本、插件及系统不同而增加,但上述标记和值应一致。端口被占用时,因为设置了 strictPort: true,进程会直接失败而不是静默换端口。

按证据定位覆盖来源

Vite 配置生效证据链

没有出现 [config-check],说明目标配置没有执行,应回到工作目录、--config 路径和配置加载错误继续查。出现标记但 command 或 mode 不符合预期,说明启动命令或模式分支错误。

标记正确但最终值不同,优先检查 CLI 参数和插件。Vite 的 config 钩子接收由配置文件与 CLI 选项合并后的原始配置,插件还能返回部分配置继续合并;configResolved 读取的是最终结果。:contentReference[oaicite:3]{index=3}

开发正常而构建异常时,分别运行开发命令和 vite build,比较 command、mode 与最终字段。配置函数在开发时收到 serve,生产构建时收到 build,条件分支写反会造成“同一配置只在某个阶段失效”。:contentReference[oaicite:4]{index=4}

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

确认配置是否生效

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通