qiming/qiming-vite-plugin-design-mode/TESTING_CLI.md

CLI 功能本地测试指南

本文档说明如何在本地测试 @xagi/vite-plugin-design-mode 的 CLI 安装和卸载功能。

前置准备

1. 确保项目已安装依赖：

npm install

2. 构建项目（编译 TypeScript 到 dist 目录）：

npm run build

这会编译所有源代码到 dist/ 目录，包括 CLI 文件。

测试方法

方法 1: 使用 npm link（推荐）

这是最接近真实使用场景的测试方法。

步骤 1: 在项目根目录创建链接

# 在项目根目录执行
npm link

这会在全局创建一个符号链接，指向当前项目。

步骤 2: 在测试项目中链接插件

# 进入测试项目目录（例如 examples/demo）
cd examples/demo

# 链接插件
npm link @xagi/vite-plugin-design-mode

步骤 3: 测试安装命令

# 在测试项目目录执行
npx @xagi/vite-plugin-design-mode install

步骤 4: 测试卸载命令

# 在测试项目目录执行
npx @xagi/vite-plugin-design-mode uninstall

方法 2: 直接使用 node 运行编译后的文件

如果不想使用 npm link，可以直接运行编译后的 CLI 文件。

步骤 1: 构建项目

npm run build

步骤 2: 在测试项目中运行 CLI

# 进入测试项目目录
cd examples/demo

# 直接运行编译后的 CLI 文件
node ../../packages/plugin/dist/cli/index.js install
# 或
node ../../packages/plugin/dist/cli/index.js uninstall

方法 3: 使用 tsx 直接运行 TypeScript 文件（开发调试）

在开发过程中，可以使用 tsx 直接运行 TypeScript 文件，无需先编译。

安装 tsx（如果还没有）

npm install -g tsx
# 或
npm install --save-dev tsx

运行 CLI

# 在项目根目录
tsx packages/plugin/src/cli/index.ts install

# 或指定工作目录为测试项目
cd examples/demo
tsx ../../packages/plugin/src/cli/index.ts install

完整测试流程示例

以下是在 examples/demo 项目中完整测试安装和卸载的流程：

1. 准备测试环境

# 在项目根目录构建
npm run build

# 进入测试项目
cd examples/demo

# 备份当前的 vite.config.ts（可选）
cp vite.config.ts vite.config.ts.backup

# 备份 package.json（可选）
cp package.json package.json.backup

2. 测试安装功能

# 方法 A: 使用 npm link
npm link @xagi/vite-plugin-design-mode
npx @xagi/vite-plugin-design-mode install

# 方法 B: 直接运行编译后的文件
node ../../packages/plugin/dist/cli/index.js install

# 方法 C: 使用 tsx（开发时）
tsx ../../packages/plugin/src/cli/index.ts install

验证安装结果：

1. 检查 package.json 中是否添加了 @xagi/vite-plugin-design-mode 依赖
2. 检查 vite.config.ts 中是否添加了：
   • import appdevDesignMode from '@xagi/vite-plugin-design-mode';
   • appdevDesignMode() 在 plugins 数组中

3. 测试卸载功能

# 使用相同的方法运行卸载命令
npx @xagi/vite-plugin-design-mode uninstall
# 或
node ../../packages/plugin/dist/cli/index.js uninstall
# 或
tsx ../../packages/plugin/src/cli/index.ts uninstall

验证卸载结果：

1. 检查 package.json 中是否移除了 @xagi/vite-plugin-design-mode 依赖
2. 检查 vite.config.ts 中是否移除了：
   • import 语句
   • appdevDesignMode() 调用

4. 恢复测试环境（可选）

# 如果需要恢复到原始状态
cp vite.config.ts.backup vite.config.ts
cp package.json.backup package.json

测试不同场景

场景 1: 全新安装（插件未安装）

1. 确保测试项目的 package.json 中没有 @xagi/vite-plugin-design-mode
2. 确保 vite.config.ts 中没有相关配置
3. 运行 install 命令
4. 验证插件已安装且配置已添加

场景 2: 升级已安装的插件

1. 先在测试项目中安装旧版本（如果有）
2. 运行 install 命令
3. 验证插件已升级到最新版本

场景 3: 卸载已安装的插件

1. 确保插件已安装
2. 运行 uninstall 命令
3. 验证插件和配置都已移除

场景 4: 测试不同的包管理器

在不同使用不同包管理器的项目中测试：

# npm 项目
cd examples/basic
node ../../packages/plugin/dist/cli/index.js install

# pnpm 项目
cd examples/demo  # 如果有 pnpm-lock.yaml
node ../../packages/plugin/dist/cli/index.js install

# yarn 项目（如果有 yarn.lock）
node ../../packages/plugin/dist/cli/index.js install

调试技巧

查看详细输出

CLI 工具会输出详细的执行信息，包括：

• 检测到的包管理器
• 插件安装状态
• 执行的命令
• 配置文件修改情况

检查编译后的文件

确保 CLI 文件已正确编译：

# 检查 dist/cli 目录
ls -la dist/cli/

# 应该看到：
# - index.js
# - install.js
# - uninstall.js

常见问题排查

1. 命令未找到

   • 确保已运行 npm run build
   • 检查 packages/plugin/dist/cli/index.js 是否存在
   • 如果使用 npm link，确保已正确链接

2. 权限问题

   • 确保有写入 package.json 和 vite.config.ts 的权限

3. 配置文件格式问题

   • CLI 会尝试处理不同的代码风格，但某些复杂格式可能需要手动调整

自动化测试脚本（可选）

可以创建一个测试脚本来自动化测试流程：

#!/bin/bash
# test-cli.sh

echo "构建项目..."
npm run build

echo "进入测试项目..."
cd examples/demo

echo "测试安装..."
node ../../packages/plugin/dist/cli/index.js install

echo "等待 2 秒..."
sleep 2

echo "测试卸载..."
node ../../packages/plugin/dist/cli/index.js uninstall

echo "测试完成！"

保存为 test-cli.sh，然后运行：

chmod +x test-cli.sh
./test-cli.sh