# @eventra\_dev/cli-plugin-vue 中文文档

规范地址：https://npmcn.com/package/%40eventra_dev/cli-plugin-vue/

版本：1\.3\.3
npm 元数据更新时间：2026-11-14T07:25:08.050Z
中文译文更新时间：2026-11-14T10:13:45.748Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eventra_dev/cli-plugin-vue
原文对照：https://npmcn.com/package/%40eventra_dev/cli-plugin-vue/?lang=original
项目主页：https://eventra.dev/
源码仓库：https://github.com/and-1991/eventra-cli-plugin-vue

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：71.1 kB，21 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：3 个
- 首次发布：2026-07-22T16:57:04.665Z
- 最新版本发布：2026-11-14T07:25:07.710Z
- 近 30 天下载量：2075（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

Eventra CLI 插件 — 从 Vue SFC (.vue) 文件提取音轨() 调用

## 安装

```sh
npm install @eventra_dev/cli-plugin-vue
```

也可以使用：`pnpm add @eventra_dev/cli-plugin-vue`、`yarn add @eventra_dev/cli-plugin-vue`、`bun add @eventra_dev/cli-plugin-vue`

## README

![](https://npmcn.com/package/%40eventra_dev/cli-plugin-vue/assets/eventra-icon-animated.svg)

# Eventra CLI 插件 — Vue

[![npm version](https://img.shields.io/npm/v/@eventra_dev/cli-plugin-vue.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/@eventra_dev/cli-plugin-vue) [![npm downloads](https://img.shields.io/npm/dm/@eventra_dev/cli-plugin-vue.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/@eventra_dev/cli-plugin-vue) ![tests passing](https://img.shields.io/badge/tests-165%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white) ![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&logo=vitest&logoColor=white) ![node](https://img.shields.io/node/v/@eventra_dev/cli-plugin-vue?style=flat-square&color=darkgreen&logo=node.js&logoColor=white) [![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) ![license](https://img.shields.io/npm/l/@eventra_dev/cli-plugin-vue?style=flat-square&color=lightgrey)

公务 [**偶数CLI**](https://www.npmjs.com/package/@eventra_dev/eventra-cli) 插件 — 摘录 `track()` 从Vue 单文件组件打来的电话(`.vue`),这样 `eventra sync`编号 :`check`编号 :`watch` 理解 Vue 和 Nuxt 代码的方式与他们已经理解的普通类型脚本相同.

* * *

## 概览

CLI 核心是框架不可知的,只行走 TypeScript 和 JavaScript 文件(`.ts`, (中文(简体) ), `.tsx`, (中文(简体) ), `.mts`, (中文(简体) ), `.cts`, (中文(简体) ), `.js`, (中文(简体) ), `.jsx`, (中文(简体) ), `.mjs`, (中文(简体) ), `.cjs`) (中文(简体) ). 此插件教它 `.vue`: 它用真实的 Vue 编译器来解析每个 SFC([`@vue/compiler-sfc`](https://www.npmjs.com/package/@vue/compiler-sfc)) - 不是 regex - 并给 CLI 每个文件一个单一的虚拟TypeScript 模块,因此每个现有的检测规则(直接SDK调用,功能包接,跨文件传播,动态名称报告)适用于Vue 代码,核心引擎中没有任何Vue 特例.

Vue 和 Nuxt 数据 `.vue` 文件的处理方式相同 — Nuxt pages/layouts/ 组件是普通的Vue SFC. 见 [坚果](https://npmcn.com/package/%40eventra_dev/cli-plugin-vue/#readme-nuxt) 下面为自动进口可堆肥.

* * *

## 安装

```bash
npm install -D @eventra_dev/cli-plugin-vue @eventra_dev/eventra-cli
# or
pnpm add -D @eventra_dev/cli-plugin-vue @eventra_dev/eventra-cli
```

启用于 `eventra.json`数字 :

```json
{
  "plugins": ["@eventra_dev/cli-plugin-vue"],
  "sync": {
    "include": ["**/*.{ts,tsx,js,jsx}"],
    "exclude": ["node_modules", "dist", ".next", ".git"]
  }
}
```

`sync.include` 已经 **没有** 需求 `**/*.vue` 手动添加——插件通过 `includeGlobs`。 。 。 .

* * *

## 检测到什么

### `<script>` 编号 : `<script setup>`

处理得跟普通的一样 `.ts` 文件 — 直接 SDK 呼叫、 函数包、 变量、 三进制、 交叉文件传播 全部应用 :

```vue
<script setup lang="ts">
import { Eventra } from "@eventra_dev/eventra-sdk";

const tracker = new Eventra({ apiKey: "YOUR_PROJECT_API_KEY" });

tracker.track("checkout.started");
</script>
```

`<script>` + 键 `<script setup>` 在同一文件中,按源顺序合并. `defineProps`编号 :`defineEmits`编号 :`defineExpose`编号 :`defineOptions`编号 :`withDefaults` 穿过未受伤害.

### `<template>` ——字面事件属性

```vue
<template>
  <Button event="checkout.cta" />
</template>
```

### `<template>` ——动态事件属性

```vue
<template>
  <Button :event="computedEventName" />
</template>
```

该表达式作为-is被复制到与脚本相同的模块范围. 如果它解决了真正的脚本级常数,则事件名称通常会被检测出;否则它被报告为一种 **动态发生** (机制与 `tracker.track(someVariable)` 在平版Script)中,而不是默默地投放.

### 外部块

`<script src="./logic.ts">` 财务报告和审定财务报表 `<template src="./view.html">` 解析后从磁盘中读取.

* * *

### `<template>` - 调用处理器和表达式

模板本身所写的追踪电话不仅被读取 `event` 属性 :

```vue
<template>
  <button @click="() => { open(); trackEvent('plan:cogm_open', { id }) }">Open</button>
  <p>{{ trackEvent('panel:viewed') }}</p>
</template>
```

读取: `@click` 编号 : `v-on` 处理器(一个或多个语句,多行箭头函数), `{{ }}` 插入,来源 `v-for` (单位:千美元)`item in items()`),动态参数(`:[name()]`, (中文(简体) ), `@[event()]`和表达方式 `v-bind`, (中文(简体) ), `v-if`, (中文(简体) ), `v-else-if`, (中文(简体) ), `v-show`, (中文(简体) ), `v-model`, (中文(简体) ), `v-html` 财务报告和审定财务报表 `v-text`。它们被放在与脚本相同的模块中,所以导入或定义的函数通常会解决;一个参数来自 `v-for` 变量报告为动态发生。 循环变量 `v-for` 财务报告和审定财务报表 `v-slot` 参数不是代码,而是被跳过;自定义指令的值(`v-focus="x"`)为孤.

### 部件的道具,无论它们被称作什么

这道具不用命名 `event`。如果一个组件向一个跟踪呼叫发送一个道具,那么每个使用该道具有值的组件的地方都是事件:

```vue
<!-- Button.vue -->
<script setup lang="ts">
import { Eventra } from '@eventra_dev/eventra-sdk'
const tracker = new Eventra({ apiKey: 'YOUR_KEY' })
const props = defineProps<{ analyticsName: string }>()
function onClick() { tracker.track(props.analyticsName) }
</script>
<template><button @click="onClick"><slot /></button></template>

<!-- Page.vue -->
<script setup lang="ts">
import Button from './Button.vue'
</script>
<template><Button analytics-name="checkout.cta">Pay</Button></template>
```

`checkout.cta` 已找到。 和我们一起工作 `defineProps<{ ... }>()`, (中文(简体) ), `defineProps([...])`, (中文(简体) ), `defineProps({ ... })`, (中文(简体) ), `withDefaults(...)`,道具对象(`const props = defineProps(...)`)和分解(`const { analyticsName } = defineProps(...)`),也当模板用其赤名读取道具时(`@click="tracker.track(analyticsName)"`) (中文(简体) ). 将道具交给另一部件(`<Inner :name="props.analyticsName" />`页:1 支持组件永远不是事件 。 一个道具来自一个 `v-for` 变量报告为动态发生。 由保留词命名的道具(`class`, (中文(简体) ), `for`, (中文(简体) ), `default`, (中文(简体) ), `new`)不打破扫描;通过道具对象读取(`props.class`),因为模板也必须读取.

**未跟踪** (这些组件像以前一样被扫描,因此没有丢失,但找不到只使用它们的道具):

-   选项 API 组件 `export default` 其最后声明不是 `<script>`,其 `props` 不在对象中被写出(`props: sharedProps`)或谁的 `this` 在巢穴内读取 `function` (一箭所持. 组件为 `props: [...]` 或者说 `props: { ... }` 财务报告和审定财务报表 `this.x` 其方法是否遵循 `defineComponent`。 。 。 .
-   `v-bind="obj"` 何时 `obj` 不是一个分析可看到的对象(调用、页面参数); 写出或保存在 `const` 被读取,在道具中的位置.
-   按名称登记而不是进口的部件和动态部件`<component :is="X">`) (中文(简体) ).
-   Nuxt 自动进口组件(使用时无) `import`:标记与其文件不匹配.
-   一个正常的部件 `<script>` 拥有自己的 `export default`,一个 `export` 类型以外的 `<script setup>`,在其它代码后导入,或 `src=` 剧本.

CLI 无法解析到纯字符串的值( a) `v-for` 变量,页本身的道具)列在"Dynamic event names"下,而不是成为事件,原因(`env`, (中文(简体) ), `variable`, (中文(简体) ), `template`, (中文(简体) ), `call`, (中文(简体) ), `expression`) (中文(简体) ). 组件本身内部的追踪呼叫被单独列出,列在"包裹内"下,因为它追踪的是每个呼叫者通过的任何内容;通过一字的呼叫者仍然被找到.

## `watch` 和外部文件

`<script src="...">` 财务报告和审定财务报表 `<template src="...">` 指向其它文件. `eventra sync`, (中文(简体) ), `check` 财务报告和审定财务报表 `eventra watch` 读取 `watch` 当其中一个文件更改时重新扫描组件( 插件告诉文件创建的 CLI ) .

## JSX 中的脚本和没有的链接文件

脚本 `lang="tsx"` 或者说 `lang="jsx"` 被读取为TSX,因此其JSX不是一个语法错误. A 类 `<script src>` 或者说 `<template src>` 其文件不存在的,从CLI获得注释(它持有的东西不在扫描中). 链接中的语法错误 `<script src>` 文件报告于 `.vue` 与链接文件的行相连接.

## 其他语言模板

A 类 `<template lang="pug">` (或 `jade`, (中文(简体) ), `haml`, (中文(简体) ), `slm`)不是 HTML 标记,而是不读: 插件返回 CLI 扫描后打印的注释, 文件的 `<script>` 照常阅读。 一个空的 `event=""` 模板中的属性在无注释的情况下被跳过. `v-memo` 读作像 `v-if` 以及持有密码的其他指令.

## 坚果

Nuxt 页面、布局和组件为普通 `.vue` SFCs——解析相同,不需要额外配置.

无明确内容自动进口的可编组件 `import` 语句( Nuxt 的自可调值,或您的自可调值) `composables/`编号 :`utils/`)旨在解决 **一旦项目运行 `nuxt prepare`编号 :`nuxt dev`** (这样) `.nuxt/` 存在并被接入 `tsconfig.json` - CLI分析项目的真实性 `tsconfig.json`,因此Nuxt生成的环境类型与任何其他TypeScript项目一样可见. 主机CLI的解析器理解 `declare const x: typeof import("./module")["name"]` 形状 Nuxt/`unplugin-auto-import` 生成这些绑定物(由单位测试覆盖,并用该环境形状的手写固定件,并手动核实结束于真实的 Nuxt 3 项目: `nuxt prepare`,呼叫自动进口的可容可容可容可装 `track()` 检测到的未明确 `import`; 无 `.nuxt/` 同一项目不产生任何事件)。 端对端检查是人工的,不是自动测试套件的一部分.

* * *

## 配置

没有指定插件配置 —— 它纯粹通过在 `eventra.json`是因为 `plugins` 阵列( 见 [安装](https://npmcn.com/package/%40eventra_dev/cli-plugin-vue/#readme-installation)) (中文(简体) ).

* * *

## 插件合同

```ts
export interface CliPluginVue {
  readonly id: string;
  readonly version: string;
  readonly includeGlobs: readonly string[];
  readonly staticSinks?: readonly CliPluginStaticCalleeSink[];
  match(path: string): boolean;
  transform(input: { path: string; source: string }): Promise<{
    modules: Array<{ path: string; content: string }>;
    notes?: string[];      // e.g. a `<template lang="pug">` that is not read, a `src=` file that is not there
    dependsOn?: string[];  // `<script src>` / `<template src>` files, so `watch` rescans the component
  }>;
}
```

无依赖 `@eventra_dev/eventra-cli` - CLI在内部适应这个形状. `.vue` - 一个虚拟 `.vue.ts` 模块(编译脚本内容,然后是每个模板的功能包合成调用) `event="..."` 从模板复制的处理器、插件和指令表达式 `// --- vue template (auto-generated) ---` 注释 CLI 用于从您自己的行中分辨生成代码 . `staticSinks` 说明这些合成电话; CLI从中自行建造了下沉探测器. 见 [`@eventra_dev/eventra-cli`插件文件](https://www.npmjs.com/package/@eventra_dev/eventra-cli#plugin-contract-for-authors) 为完整的外部插头合同.

* * *

## 所需资源

-   节点.js 18+
-   `@eventra_dev/eventra-cli` 作为主机 CLI

* * *

## 测试范围

**说明/处/职能/线路覆盖率100%** (v8供应商, `pnpm test:coverage`),通过a执行 `coverage.thresholds` 块中 `vitest.config.ts`。 。 。 .

**164个单元测试** (最高),涵盖:

| 区域 | 封面 |
| --- | --- |
| SFC 分析 | 脚本 + 脚本设置合并顺序, 注释安全 , `src=` 外部文件 |
| 模板——文字 | 薄膜元素, `v-if`编号 :`v-for`,槽,多个模板根 |
| 模板——动态 | 原始表达式传递, 通过合并的脚本范围解析 |
| 脚本设置宏 | 所有五个编译器宏( E)`defineProps`编号 :`defineEmits`编号 :`defineExpose`编号 :`defineOptions`编号 :`withDefaults`(没有特殊标记的通过) |
| 组件道具 | `defineProps` 在每一个拼写中,通过一个对象读取道具,一个解构和赤裸的模板名称,用道具调用的儿童组件,标签的名称与进口的匹配 |
| 虚拟模块产出 | 单笔合计 `.vue.ts`,当脚本/模板为空时导出 stub |
| 插件合同 | `match()`, (中文(简体) ), `includeGlobs`, (中文(简体) ), `staticSinks`, (中文(简体) ), `transform()` |

Nuxt 环境自动导入形状 (`declare const x: typeof import(...)`)在主机CLI中被一个单位测试所覆盖,该测试是手写成形状. 真实的 `nuxt prepare` 工程也经过手动检查结束,但检查不是自动套件的一部分(见 [坚果](https://npmcn.com/package/%40eventra_dev/cli-plugin-vue/#readme-nuxt) 页:1.

本地运行 :

```bash
pnpm --filter @eventra_dev/cli-plugin-vue test
pnpm --filter @eventra_dev/cli-plugin-vue test:coverage
```

* * *

## 许可证

麻省理工学院,版权 (c) 2026 [尤里·克罗利克](https://github.com/and-1991)。见 [自由主义](https://npmcn.com/package/%40eventra_dev/cli-plugin-vue/LICENSE)。 。 。 .

## 常见问题

### @eventra\_dev/cli-plugin-vue 是什么？

Eventra CLI 插件 — 从 Vue SFC \(\.vue\) 文件提取音轨\(\) 调用

### 如何安装 @eventra\_dev/cli-plugin-vue？

在项目目录运行 npm install @eventra\_dev/cli-plugin-vue，或使用 pnpm add / yarn add / bun add。

### @eventra\_dev/cli-plugin-vue 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eventra\_dev/cli-plugin-vue 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @eventra\_dev/cli-plugin-vue 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @eventra\_dev/cli-plugin-vue 可以商用吗？

@eventra\_dev/cli-plugin-vue 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eventra\_dev/cli-plugin-vue 的下载量有多少？

根据 npm 官方下载统计，@eventra\_dev/cli-plugin-vue 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,075 次，日均约 69 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eventra\_dev/cli-plugin-vue 还在维护吗？

最新版本 1\.3\.3 发布于 2026/11/14（今天）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/07/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。