安装与使用

eastspire2026/5/15大约 4 分钟euvuirustwasmcliinstall

安装

cargo install euv-cli

提示

安装的包名为 euv-cli，但安装后的可执行文件名为 euv。

命令格式

euv 支持三种子命令：run / build / fmt：

# 构建 + 文件监视 + 开发服务器
euv run [选项]

# 仅构建
euv build [选项]

# 格式化 euv 宏调用
euv fmt [选项]

run 和 build 命令后可附加 wasm-pack 参数，使用 -- 分隔：

# 传递 wasm-pack 参数
euv run --crate-path ./example --www-dir ./www -- --target web

# 仅构建
euv build --crate-path ./example --www-dir ./www -- --target web

使用示例

# 运行（开发构建 + 热重载服务器）
euv run --crate-path ./example --www-dir ./www --port 80

# 仅构建（开发构建）
euv build --crate-path ./example --www-dir ./www

# 发布构建 + 服务器
euv run --crate-path ./example --www-dir ./www --port 80 --release

# 性能分析构建
euv run --crate-path ./example --www-dir ./www --port 80 --profiling

# 传递其他 wasm-pack 参数（如 --out-dir）
euv run --crate-path ./example --www-dir ./www -- --out-dir www/pkg

# 格式化 euv 宏调用（html!、class!、css_vars!、watch!）
euv fmt --path ./src

# 检查格式化是否需要（不修改文件）
euv fmt --path ./src --check

# 通过 cargo 运行
cargo run -p euv-cli -- run --crate-path ./example --www-dir ./www --port 80

run/build 命令行参数

	参数	简写	默认值
`--crate-path`	`-c`	`.`	Rust crate 路径
`--www-dir`		`www`	静态文件目录（相对于 crate-path）
`--port`	`-p`	`80`	开发服务器端口
`--index-html`			自定义 index.html 模板文件路径
`--dev`			创建开发构建（启用调试信息，禁用优化）
`--release`			创建发布构建（启用优化，禁用调试信息）
`--profiling`			创建性能分析构建（启用优化和调试信息）
`-- ...`			透传给 `wasm-pack build` 的参数

构建模式优先级

构建模式通过 --dev、--release、--profiling 标志指定，优先级如下：

--profiling — 性能分析构建（最高优先级）
--release — 发布构建
--dev — 开发构建
如果未指定任何标志，还会检查 -- 后的 wasm-pack 参数中是否包含 --profiling 或 --release
默认为开发构建（--dev）

提示

推荐使用 --dev/--release/--profiling 标志代替通过 -- 透传 --release 给 wasm-pack，前者语义更清晰且与构建管道深度集成（如 HTML 生成会根据构建模式调整）。

fmt 命令行参数

	参数	简写	默认值	说明
`--path`	`-p`	`.`	要格式化的目录或文件路径
`--check`		`false`	仅检查是否需要格式化，不修改文件

启动流程

euv 在启动时会自动执行以下操作：

自动格式化 — 启动时会先对 src 目录下的所有 .rs 文件执行内置格式化（支持 html!、class!、css_vars!、var! 宏）
WASM 构建 — 执行 wasm-pack build --target web 编译项目
开发服务器 — 仅 run 模式启动，自动注入热重载脚本并开启文件监视

自动生成 index.html

如果 www-dir 目录下不存在 index.html，euv 会自动生成一个默认模板：

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>euv app</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module">
      import init, { main } from './pkg/euv_example.js';
      await init();
      main();
    </script>
  </body>
</html>

提示

你可以在 www 目录下放置自定义的 index.html，euv 会在其中注入热重载脚本（在 </body> 标签前），无需手动添加。

自定义 index.html 模板

通过 --index-html 参数指定自定义的 index.html 模板文件，替代内置的默认模板：

euv run --crate-path ./example --www-dir ./www --index-html ./my-template.html

模板文件中支持以下占位符：

	占位符	说明
`__IMPORT_PATH__`	替换为 WASM 模块的导入路径
`__RELOAD_ROUTE__`	替换为热重载的 SSE 路由地址

示例模板：

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>My Custom App</title>
    <link rel="stylesheet" href="styles.css" />
  </head>
  <body>
    <div id="app"></div>
    <script type="module">
      import init, { main } from '__IMPORT_PATH__';
      await init();
      main();
    </script>
  </body>
</html>

提示

--index-html 指定的是模板文件路径，euv 会读取该文件并替换占位符后输出到 www-dir 目录。与直接在 www-dir 下放置 index.html 不同，使用模板方式可以在构建时动态注入正确的导入路径和热重载路由。

访问应用

启动后在浏览器中访问：

http://127.0.0.1:<port>/<www-dir>/index.html

例如使用默认参数时：

http://127.0.0.1:80/www/index.html

注

访问路径中的 <www-dir> 与 --www-dir 参数值一致。如果 --www-dir 设为 static，则访问 http://127.0.0.1:80/static/index.html。

.gitignore 过滤

euv 会读取项目根目录（--crate-path 指定的路径）下的 .gitignore 文件，自动忽略被排除的文件变更事件，避免不必要的重新编译。