这篇内容是在有道云旧笔记基础上重新整理的 Vue/Vite 工程实践 笔记。原始记录偏碎片化，这里补充了使用场景、阅读顺序和落地时需要注意的边界，方便以后在项目里快速复用。

适用场景 ​

  • Vue/Vite 项目中遇到配置、组件封装、构建或运行时问题时，作为排查入口。
  • 需要把一次性调试经验沉淀成团队内可复用的前端工程实践。
  • 迁移旧项目或升级依赖时，用来对照检查环境变量、插件和组件行为差异。

核心要点 ​

  • 正文已经按 「自定义指令」 等小节组织，阅读时可以先定位到当前问题对应的小节。
  • 保留了 3 段可直接参考的代码或命令，主要涉及 bash、javascript，复制前需要按当前项目路径、版本和变量名做调整。
  • 涉及环境变量的示例只保留命名和加载方式，真实密钥、token 和本地配置应放在未提交的本地文件或 CI 密钥变量中。
  • 涉及命令行操作时，建议先在测试目录或测试环境执行，确认输出符合预期后再应用到生产环境。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
.env                # 在所有情况下都会加载
.env.local          # 在所有情况下都会加载，一般用来在本地开发时存敏感信息，比如 token 等，所以需要在 .gitignore 里添加它来避免上传暴露敏感信息
.env.[mode]         # 只会在特定的mode下加载
.env.[mode].local   # 只会在特定的mode下加载，同上需要在 git 中忽视

这里的.env.[mode].local 默认会覆盖 .env.[mode] 

使用 --mode + .env 文件（推荐做法）

"scripts": {
  "dev": "vite --mode dev",
  "build:android": "vite build --mode android",
  "build:pc": "vite build --mode pc"
}

# .env.android
VITE_PLATFORM=android
VITE_THEME=dark

# .env.pc
VITE_PLATFORM=pc
VITE_THEME=light

自定义指令 ​

您可以使用 defineDirective 定义自己的指令。

以内置指令为例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
export const MessageDirective = defineDirective<MessageToken, MessageStatement>(context => ({
  lex(comment) {
    return simpleMatchToken(comment, /#(error|warning|info)\s*(.*)/)
  },
  parse(token) {
    if (token.type === 'error' || token.type === 'warning' || token.type === 'info') {
      this.current++
      return {
        type: 'MessageStatement',
        kind: token.type,
        value: token.value,
      }
    }
  },
  transform(node) {
    if (node.type === 'MessageStatement') {
      switch (node.kind) {
        case 'error':
          context.logger.error(node.value, { timestamp: true })
          break
        case 'warning':
          context.logger.warn(node.value, { timestamp: true })
          break
        case 'info':
          context.logger.info(node.value, { timestamp: true })
          break
      }
      return createProgramNode()
    }
  },
  generate(node, comment) {
    if (node.type === 'MessageStatement' && comment)
      return `${comment.start} #${node.kind} ${node.value} ${comment.end}`
  },
}))

实践检查清单 &#8203;

  • 先确认 Vue、Vite、Node、包管理器版本，再判断示例是否需要按当前工程结构调整。
  • 涉及构建或插件配置时，建议同时验证开发环境和生产构建结果。
  • 不要把真实 token、密码、私钥或本地 .env.local 提交到仓库。
  • 涉及 UI 或浏览器行为时，至少在桌面端和移动端各验证一次关键路径。
  • 涉及接口、服务端或权限逻辑时，补充失败分支和权限边界测试。

复盘小结 &#8203;

这篇笔记更适合作为问题排查或方案落地前的速查材料。后续如果在真实项目中再次遇到同类问题，可以继续把具体版本、报错信息、最终取舍和验证结果补到对应小节里，让它从代码片段逐步沉淀成完整方案。