@linyjs/cli - linyjs 框架命令行工具

📦 简介

@linyjs/cli 是 linyjs 框架的官方命令行工具，提供零配置的插件打包功能。

核心理念：

• ✅ 零配置 - 无需配置 webpack、rollup 等构建工具
• ✅ 智能构建 - CLI 自动处理所有构建细节
• ✅ 开箱即用 - 只需编写 TypeScript/TSX 代码即可打包
• ✅ 优化默认值 - 内置 esbuild，自动 bundle、minify、tree shaking

🚀 快速开始

安装

# 全局安装（推荐）
npm install -g @linyjs/cli

# 或在项目中使用
npx @linyjs/cli <command>

基本用法

# 查看帮助
npx @linyjs/cli

# 创建新插件项目
npx @linyjs/cli init my-plugin

# 打包插件
cd my-plugin
npx @linyjs/cli pack

# 开发模式（打包 + 安装 + 注册）
npx @linyjs/cli dev

# 验证插件
npx @linyjs/cli validate my-plugin.mpk

📖 命令参考

pack - 打包插件

将插件项目打包为 .mpk 文件。

用法

npx @linyjs/cli pack [options]

选项

| 选项 | 简写 | 类型 | 默认值 | 说明 | |------|------|------|--------|------| | --output | -o | string | . | 输出目录 | | --name | -n | string | - | 插件名称（覆盖 package.json） | | --version | -v | string | - | 版本号（覆盖 package.json） | | --build | - | boolean | true | 执行构建步骤（使用 --no-build 跳过） | | --manifest | - | string | - | 自定义 manifest.json 路径 | | --verbose | - | boolean | false | 显示详细日志 |

示例

# 基本用法
npx @linyjs/cli pack

# 指定输出目录
npx @linyjs/cli pack -o ./releases

# 跳过构建（已有 dist/）
npx @linyjs/cli pack --no-build

# 详细模式
npx @linyjs/cli pack --verbose

# 自定义版本
npx @linyjs/cli pack -v 1.0.0

工作流程

1. 读取 package.json
2. 执行构建（npm run build）
3. 生成 manifest.json
4. 验证插件结构
5. 打包为 .mpk 文件
6. 显示结果统计

dev - 开发模式 ⭐

快速开发工作流：打包插件 → 安装到 extensions → 注册到 packages.json

用法

npx @linyjs/cli dev [options]

选项

| 选项 | 简写 | 类型 | 默认值 | 说明 | |------|------|------|--------|------| | --target | -t | string | 自动检测 | extensions 目录路径 | | --verbose | - | boolean | false | 显示详细日志 |

工作流程

1. 打包插件（生成 .mpk）
2. 解压到 extensions/<plugin-name>/
3. 读取 manifest.json
4. 更新 packages.json
5. 清理临时文件

示例

# 基本用法（自动检测 extensions 目录）
npx @linyjs/cli dev

# 指定目标目录
npx @linyjs/cli dev --target /path/to/ling/packages/ssr/extensions

# 详细模式
npx @linyjs/cli dev --verbose

输出示例

🚀 linyjs Plugin Dev Mode

✔ Packing plugin...
✔ Plugin packed: my-plugin-1.0.0.mpk
✔ Installing to extensions...
✔ Installed to: /path/to/extensions/my-plugin
✔ Registering plugin...
✔ Plugin registered in packages.json

✓ Development setup complete!

Plugin installed:
  Name: my-plugin
  Path: /path/to/extensions/my-plugin
  Status: enabled

Next steps:
  1. Restart SSR server:
     cd packages/ssr && npx tsx src/demo/dev-server-with-pkg.tsx
  2. Or use hot reload (if supported)
  3. Test your plugin in the browser

优势

✅ 一键部署 - 无需手动复制文件
✅ 自动注册 - 自动更新 packages.json
✅ 智能检测 - 自动查找 extensions 目录
✅ 增量更新 - 覆盖旧版本，保留配置
✅ 清理临时文件 - 不留下垃圾文件

init - 创建项目 ⭐

从 npm 下载模板，快速创建新的插件项目。

用法

npx @linyjs/cli init [name]

参数

• name - 项目名称（默认：my-plugin）

示例

# 创建名为 my-blog 的插件项目
npx @linyjs/cli init my-blog

# 使用默认名称
npx @linyjs/cli init

工作流程

1. 从 npm 下载 @linyjs/plugin-templates
2. 创建项目目录
3. 复制模板文件
4. 显示下一步操作指南

输出示例

🚀 linyjs Plugin Project Creator

✔ Downloading template from npm...
✔ Template downloaded

✓ Project created successfully!

Next steps:
  1. Navigate to your project:
     cd my-plugin
  2. Install dependencies:
     npm install
  3. Start development:
     npm run dev
  4. Pack for deployment:
     npx @linyjs/cli pack

Learn more:
  - Plugin Development Guide: ...
  - CLI Documentation: ...

模板内容

创建的插件项目包含：

my-plugin/
├── package.json          # 预配置的依赖和脚本
├── tsconfig.json         # TypeScript 配置
├── README.md             # 项目说明
├── .gitignore            # Git 忽略文件
└── src/
    ├── server/
    │   └── index.ts      # 服务端模块示例
    └── client/
        └── index.tsx     # 客户端模块示例

特性：

• ✅ TypeScript 支持
• ✅ React 19 支持
• ✅ 零配置构建（使用 @linyjs/cli）
• ✅ 示例代码和注释
• ✅ 开箱即用

validate - 验证插件

验证 .mpk 文件或插件目录是否符合规范。

用法

npx @linyjs/cli validate <path> [options]

参数

• path - 插件路径（.mpk 文件或目录）

选项

| 选项 | 简写 | 类型 | 默认值 | 说明 | |------|------|------|--------|------| | --strict | - | boolean | false | 严格模式（警告也报错） | | --json | - | boolean | false | JSON 格式输出 |

示例

# 验证目录
npx @linyjs/cli validate ./my-plugin

# 验证 .mpk 文件
npx @linyjs/cli validate my-plugin.mpk

# JSON 输出
npx @linyjs/cli validate my-plugin.mpk --json

init - 初始化项目

快速创建新的插件项目模板。

用法

npx @linyjs/cli init [name] [options]

参数

• name - 项目名称（可选）

选项

| 选项 | 简写 | 类型 | 默认值 | 说明 | |------|------|------|--------|------| | --template | -t | string | minimal | 项目模板 | | --yes | -y | boolean | false | 跳过确认 |

可用模板

• minimal - 最小化插件（Hello World）
• full - 完整功能插件
• admin-extension - 管理后台扩展
• api-service - 纯 API 服务

示例

# 交互式创建
npx @linyjs/cli init

# 指定名称和模板
npx @linyjs/cli init my-blog --template=full

# 非交互模式
npx @linyjs/cli init my-plugin -t minimal -y

💡 使用场景

1. 本地开发

方式 A：使用 dev 命令（推荐）⭐

# 在插件项目中
cd my-plugin

# 一键打包、安装、注册
npx @linyjs/cli dev

# 重启 SSR 服务器即可看到效果
cd ../ssr && npx tsx src/demo/dev-server-with-pkg.tsx

优势：

• ✅ 自动打包
• ✅ 自动复制到 extensions
• ✅ 自动注册到 packages.json
• ✅ 清理临时文件

方式 B：手动流程

# 在插件项目中
cd my-plugin

# 打包并测试
npx @linyjs/cli pack

# 复制到 extensions 目录
cp my-plugin-1.0.0.mpk ../ssr/extensions/

# 重启 SSR 服务器
cd ../ssr && npx tsx src/demo/dev-server-with-pkg.tsx

2. CI/CD 集成

# .github/workflows/build.yml
name: Build Plugin

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Pack plugin
        run: npx @linyjs/cli pack --output ./dist
      
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: plugin
          path: ./dist/*.mpk

3. 批量处理

# 打包多个插件
for dir in plugins/*/; do
  cd "$dir"
  npx @linyjs/cli pack -o ../../releases/
  cd ../..
done

🔧 配置

.lingrc.json

可以在项目根目录创建 .lingrc.json 配置文件：

{
  "build": {
    "command": "npm run build",
    "outputDir": "dist"
  },
  "pack": {
    "exclude": [
      "node_modules",
      ".git",
      "*.test.ts",
      "*.spec.ts"
    ],
    "include": [
      "**/*"
    ]
  },
  "manifest": {
    "customFields": {
      "homepage": "https://example.com"
    }
  }
}

🎨 输出示例

成功打包

📦 linyjs Plugin Packer

✔ Package.json loaded
✔ Build completed
✔ Manifest generated
✔ Structure validated
✔ Plugin packed successfully

✓ Plugin ready!
  File: /path/to/my-plugin-1.0.0.mpk
  Size: 245.67 KB
  Version: 1.0.0

Next steps:
  1. Test the plugin:
     cp /path/to/my-plugin-1.0.0.mpk /path/to/ling/packages/ssr/extensions/
  2. Restart SSR server:
     cd packages/ssr && npx tsx src/demo/dev-server-with-pkg.tsx
  3. Validate the plugin:
     npx @linyjs/cli validate /path/to/my-plugin-1.0.0.mpk

验证失败

📦 linyjs Plugin Packer

✔ Package.json loaded
✔ Build completed
✔ Manifest generated
✗ Validation failed

Validation errors:
  - Server entry not found: server/index.js
  - Client entry not found: client/index.js

🛠️ 技术栈

• Cleye - 现代化 CLI 框架
• Archiver - ZIP 压缩
• Chalk - 终端着色
• Ora - 加载动画
• FS Extra - 文件系统操作

📝 开发指南

本地开发

# 克隆仓库
git clone https://github.com/linyjs/ling.git
cd ling/packages/cli

# 安装依赖
npm install

# 构建
npm run build

# 测试
node dist/index.js pack --help

添加新命令

1. 在 src/commands/ 目录下创建新文件
2. 实现命令逻辑
3. 在 src/index.ts 中注册命令

❓ 常见问题

Q: 如何使用 dev 命令快速开发？

# 在插件项目目录中
cd my-plugin

# 一键打包、安装、注册
npx @linyjs/cli dev

# 如果自动检测失败，指定目标目录
npx @linyjs/cli dev --target /path/to/ling/packages/ssr/extensions

详见：dev - 开发模式

Q: 如何跳过构建步骤？

npx @linyjs/cli pack --no-build

Q: 如何指定输出目录？

npx @linyjs/cli pack -o ./releases

Q: 打包后文件在哪里？

默认在当前目录，文件名格式为 {name}-{version}.mpk。

Q: 如何验证插件？

npx @linyjs/cli validate my-plugin.mpk

📄 License

MIT

🔗 相关链接

• linyjs 框架文档
• 插件开发指南
• 问题反馈