crabatool

v1.0.845

Published

6 days ago

crabatool

0High
0Medium
0Low

crabatool 是一个基于 Node.js 的前端工程化脚手架工具，主要服务于 Craba/NGP 前端项目体系。支持命令行（CLI）和 JS 配置文件两种使用方式，兼容 Windows、macOS、Linux，可集成 Jenkins 实现自动化构建。

当前版本：1.0.844

环境要求

Node.js：需要先安装 Node.js LTS版本
支持平台：Windows、macOS、Linux

验证安装

# 验证Node.js和npm安装
node --version
npm --version

# 验证crabatool安装
crabatool -v

# 查看帮助信息
crabatool --help

安装

全局安装（推荐）：

npm install crabatool -g

从内网仓库安装（更快）：

npm install crabatool -g --registry http://172.17.0.236:4873/

全局安装一次后，在任意路径下都可以直接使用 crabatool 命令。后续更新执行 npm install crabatool -g 或 npm update crabatool -g 即可。

快速上手

5分钟快速体验

# 第一步：安装crabatool（只需一次）
npm install crabatool -g --registry http://172.17.0.236:4873/

# 第二步：创建项目目录
mkdir my-craba-app && cd my-craba-app

# 第三步：安装框架
crabatool -install -webPath .

# 第四步：使用agent或大模型创建首页相关的文件：craba框架的index.html模板创建入口文件、Main.gspx、其要业务相关的文件

# 第五步：启动开发服务器
crabatool -run -webPath . -port 8080

# 第六步：打开浏览器访问
# http://localhost:8080

恭喜！ 您已经成功启动了第一个Craba项目。

常用命令示例

# 显示帮助信息（进入交互式菜单）
crabatool

# 安装项目平台资源
crabatool -install -webPath F:\myproject\www

# 更新项目平台资源
crabatool -update -webPath F:\myproject\www

# 检测项目 JS 语法
crabatool -checkjs -webPath F:\myproject\www -modName mymod

# 启动本地开发服务器
crabatool -run -webPath F:\myproject\www -port 9090

# 查看craba框架的最新版本号
crabatool -crabaVersion

# 查看crabatool工具的版本号
crabatool -v

命令行参数总览

通用参数

| 参数 | 说明 | |------|------| | --skip-report | 跳过系统信息上报，提高启动速度，保护隐私 | | -crabaVersion | 查看craba框架的最新版本号 | | -v | 查看crabatool工具的版本号 |

功能命令

| 命令 | 说明 | |------|------| | -install | 安装项目的 Craba 平台资源 | | -update | 更新项目的 Craba 平台资源 | | -checkjs | 检查项目 JS 语法兼容性 | | -idea | 安装/更新 IDEA 开发环境配置 | | -vscode | 安装/更新 VSCode 开发环境配置 | | -mergejs | 合并压缩指定 JS 文件 | | -mergecss | 合并压缩指定 CSS 文件 | | -mergeFiles | 将多种资源文件打包为 JSON 资源包 | | -run | 启动本地前端服务器 | | -mergeinitjs | 打包合并 init.js 和 biz.js | | -checkiconfont | 检测项目图标字体使用情况 | | -checkUpdate | 检测服务端是否标记了平台更新 | | -updateTool | 更新 crabaTool 工具自身 | | -makeHash | 生成文件的 SRI 哈希清单 | | -pageHash | 计算 gspx 页面路径的哈希值 | | -addVersion | 自动给文件添加版本号（时间戳） | | -exportgspx | 导出目录下所有 gspx 文件的标题清单 | | -autoId | 自动为 gspx 页面节点生成 ID | | -upload | 打包并上传平台资源到服务端 | | -uploadSkin | 上传 NGP 皮肤和图标库 | | -updateSkin | 更新 NGP 皮肤和图标库 | | -iconfont | 解压并部署字体库文件 | | -convertJavadoc | 转换 Javadoc HTML 文档为 JSON/MD | | -uploadDocs | 上传 Craba 知识库到服务器 | | -updateDocs | 从服务器更新 Craba 知识库 |

常用功能

1. 安装平台资源 (-install)

首次安装 Craba 平台资源到指定项目路径。

必填参数： | 参数 | 说明 | |------|------| | -webPath | 项目根路径 |

可选参数： | 参数 | 说明 | |------|------| | -version | 指定分支版本号，默认为 master |

使用示例：

# 安装主分支平台
crabatool -install -webPath F:\myproject\www

# 安装指定分支
crabatool -install -webPath F:\myproject\www -version ngp5.3

2. 启动本地服务 (-run)

启动基于 Express 的本地前端静态资源服务器，支持自动打开浏览器、文件热刷新、代理转发、gzip 压缩等。

必填参数： | 参数 | 说明 | |------|------| | -webPath | 网站根路径（login.html 或 index.html 所在目录），支持绝对路径和相对路径 | | -port | 前端服务端口号 |

可选参数： | 参数 | 说明 | |------|------| | -modName | NGP 项目的模块名称（NGP 项目必填） | | -refresh true | 开启文件变动自动刷新浏览器（监听 js/css/gspx/html 文件变动） | | -proxy | 配置 API 代理转发规则（JSON 格式字符串） | | -proxySrc | 从 JSON 文件读取代理配置 | | -noOpen true | 启动后不自动打开浏览器 | | -localLogin true | 使用本地 login.html 而非重写的登录页 | | -defaultPage | 自定义首页文件名（默认 NGP 为 login.html，其他为 index.html） | | -virtualName | 虚拟路径名 | | -childModList | 子模块列表，逗号分隔（配置后自动打包 init.js 和 biz.js） | | -ignoreCompress true | 不压缩打包后的 init.js 和 biz.js |

使用示例：

# 基本启动
crabatool -run -webPath F:\myproject\www -port 9090

# NGP 项目启动
crabatool -run -webPath F:\shell\web\src\main\resources\static\shell -port 9090 -modName shell

# 启动并开启热刷新
crabatool -run -webPath F:\myproject\www -port 9090 -refresh true

# 启动并配置代理转发
crabatool -run -webPath F:\myproject\www -port 9090 -proxy "{'/apis/':{'target':'http://127.0.0.1:8082','changeOrigin':true}}"

热刷新说明：

开启 -refresh true 后，crabatool 会通过 WebSocket 监听 js、gspx、css、html 文件的变动。
文件变动时浏览器会收到刷新消息，但会等待浏览器被激活（focus）时才真正刷新，避免高频刷新影响性能。
WebSocket 端口默认为 port + 6000（如超出端口范围会自动调整）。

文件监听功能：

启动服务时默认开启文件监听功能（enableFileWatcher），监听 .js 文件的变动并自动执行 ESLint 语法检查、编码检查、文件大小检查、ES6+ 兼容性检查。
通过配置 enableFileWatcher: false 可以关闭。

4. 更新平台资源 (-update)

从内网服务器拉取最新的 Craba 平台资源，覆盖到指定项目路径下。

必填参数： | 参数 | 说明 | |------|------| | -webPath | 项目路径 |

可选参数： | 参数 | 说明 | |------|------| | -version | 指定分支版本号，如 ngp4.7、ngp5.1、ngp5.3，默认为 master | | -progress 0 | 不显示进度条 |

使用示例：

# 更新主分支平台
crabatool -update -webPath F:\myproject\www

# 更新指定分支
crabatool -update -webPath ../web/src/main/resources/static/shell -version ngp4.7

5. JS 语法检测 (-checkjs)

对项目下所有 JS 文件进行语法兼容性检测，包括 ESLint 规则检查、编码检测、文件大小检测、ES6+ 语法检测（let/const/箭头函数/async/await/then/debugger 等），同时检查 gspx 文件中的标签使用规范。检测结果可推送到钉钉群机器人。

必填参数： | 参数 | 说明 | |------|------| | -webPath | 项目路径 |

可选参数： | 参数 | 说明 | |------|------| | -modName | 项目（模块）名称 | | -ignoreCheck | 忽略检测的目录或文件，逗号分隔，相对 webPath 的路径 | | -globals | 全局变量名列表，逗号分隔，检测时会忽略这些变量（$ 字符在 shell 中需转义为 \$） | | -webhooks | 检测报告推送地址（如钉钉群机器人 Webhook URL） | | -progress 0 | 不显示进度条（适用于 Jenkins 等 CI 环境） | | -checkgspx false | 不检查 gspx 文件 | | -checkutf8 true | 检查 UTF-8 编码 | | -checkCustomControl false | 不检查自定义控件 | | -ignoreFiles | 忽略的文件列表，逗号分隔 | | -cssFiles | 额外需要检测的 CSS 文件列表 | | -Debug true | 开启调试模式 | | -notCheckCraba true | 跳过 craba.min.js 存在性检查 |

使用示例：

# 基本检测
crabatool -checkjs -webPath F:\myproject\www -modName mymod

# 忽略特定目录和文件
crabatool -checkjs -webPath F:\myproject\www -modName mymod -ignoreCheck ueditor,iconfont,js/math.min.js

# 配置全局变量和钉钉推送
crabatool -checkjs -webPath F:\myproject\www -modName mymod -globals \$doc,CrabaMarkdown -webhooks https://oapi.dingtalk.com/robot/send?access_token=xxx

# 跳过上报且不显示进度条（CI 环境）
crabatool --skip-report -checkjs -webPath F:\myproject\www -progress 0

检测报告推送格式：

推送到 Webhook 的数据格式为：

{
  "msgtype": "markdown",
  "markdown": {
    "title": "代码检测报告",
    "text": "检测结果（markdown 格式）"
  }
}

6. 安装/更新 IDEA 环境 (-idea)

自动安装或更新 IntelliJ IDEA 的 Craba 开发环境，包括：

gspx 智能语法提示（XSD）
新建页面模板（Craba.gspx / CrabaJs.js）
gspx 文件语法高亮（关联为 XML 类型）

crabatool -idea

7. 安装/更新 VSCode 环境 (-vscode)

自动安装或更新 VSCode 的 Craba 开发环境，包括：

gspx 智能语法提示（XSD + RedHat XML 插件）
新建页面模板
快捷键配置（ctrl+alt+n、alt+j 等）

crabatool -vscode

8. 合并压缩 JS 文件 (-mergejs)

将指定的多个 JS 文件合并为一个文件，支持压缩和变量替换。

必填参数： | 参数 | 说明 | |------|------| | -inNames | 输入文件名列表，逗号分隔 | | -outName | 输出文件的完整路径 |

可选参数： | 参数 | 说明 | |------|------| | -targetPath | 输入文件的根目录（与 inNames 组合为完整路径）；不填则 inNames 需为完整路径 | | -ignorecompress true | 不压缩 JS（默认会压缩） | | -hidejspath true | 合并后的文件中不显示原始文件路径注释 | | -exp | 变量替换表达式，格式为 ${变量名}=替换值 |

使用示例：

# 合并同目录下多个 JS（压缩）
crabatool -mergejs -targetPath F:\project\js -inNames a.js,b.js -outName F:\output\merged.js

# 合并不同路径的 JS（不压缩）
crabatool -mergejs -inNames F:\js\a.js,D:\js\b.js -outName E:\output.js -ignorecompress true

# 压缩单个文件
crabatool -mergejs -targetPath F:\project\js -inNames app.js -outName F:\output\app.min.js

# 压缩并替换变量
crabatool -mergejs -targetPath F:\project\js -inNames app.js -outName F:\output\app.min.js -exp ${plugHost}=http://192.168.1.100:8082/

9. 合并压缩 CSS 文件 (-mergecss)

将指定的多个 CSS 文件合并为一个文件。

必填参数： | 参数 | 说明 | |------|------| | -inNames | 输入文件名列表，逗号分隔 | | -outName | 输出文件的完整路径 |

可选参数： | 参数 | 说明 | |------|------| | -targetPath | 输入文件的根目录 | | -ignoreCompress | 不压缩 CSS |

使用示例：

crabatool -mergecss -targetPath F:\project\skins -inNames iconfont.css,craba.min.css -outName D:\output\craba.min.css

# 不压缩
crabatool -mergecss -targetPath F:\project\skins -inNames a.css,b.css -outName D:\output\merged.css -ignoreCompress

10. 打包资源文件为 JSON (-mergeFiles)

将多种类型的资源文件（JS/CSS/gspx）压缩后以路径为 key 合并到一个 JSON 资源包中，减少 HTTP 请求。可以追加到 init.js 中或生成独立资源文件。

必填参数： | 参数 | 说明 | |------|------| | -inNames | 输入文件名列表，逗号分隔（支持 .js/.css/.gspx） |

可选参数： | 参数 | 说明 | |------|------| | -outName | 输出文件路径（独立资源包方式） | | -initJs | 追加到指定 init.js 文件中（追加方式） | | -targetPath | 输入文件的根目录 | | -modName | 模块名称（作为资源路径前缀） | | -webPath | 项目路径 | | -clearCache true | 清除缓存 |

使用示例：

crabatool -mergeFiles -modName shell -webPath F:\project\shell -targetPath F:\project\shell -inNames skins/craba.min.css,Main.gspx,Main.js,js/init.js -outName F:\project\shell\shell.res.js

# 追加到 init.js
crabatool -mergeFiles -modName jxc -webPath F:\project\jxc -targetPath F:\project\jxc -inNames skins/skin.css,js/wpsSettings.js -initJs F:\project\jxc\js\init.js

11. 查询craba框架的最新版本 (-crabaVersion)

查询服务端 Craba 框架的最新版本号和更新时间。

crabatool -crabaVersion

12. 查看crabatool工具版本 (-v)

查看当前 crabatool 工具的版本号。

使用示例：

# 查看crabatool工具的版本号
crabatool -v

13. 更新 Craba 知识库 (-updateDocs)

从服务器下载最新的 Craba 知识库文档并解压到本地目录。

必填参数： | 参数 | 说明 | |------|------| | -docsPath | 文档解压后存放的目录路径 |

使用示例：

# 从服务器更新craba文档到本地目录
crabatool -updateDocs -docsPath F:\craba-doc

其他功能

1. 打包 init.js 和 biz.js (-mergeinitjs)

将 NGP 项目模块及其子模块下的 JS 业务文件合并打包为 init.js 和 biz.js，减少 HTTP 请求。

必填参数： | 参数 | 说明 | |------|------| | -webPath | 项目路径 | | -port | 端口号 | | -modName | 模块名称 |

可选参数： | 参数 | 说明 | |------|------| | -childModList | 子模块列表，逗号分隔（如 baseinfo,recordsheet,accounting） | | -ignoreCompress | 是否跳过压缩（true 不压缩，false 压缩） | | -mergeInitAndBiz true | 将最终的 init.js 和 biz.js 合并为一个文件 | | -progress 0 | 不显示进度条 |

使用示例：

crabatool -mergeinitjs -webPath F:\myproject\www -port 9090 -modName jxc -childModList baseinfo,recordsheet,accounting -ignoreCompress false

# Jenkins 环境
crabatool -mergeinitjs -webPath /opt/project/www -port 9090 -modName shell -childModList baseinfo,recordsheet -ignoreCompress false -progress 0

工作原理： 工具会先打包当前模块 模块名/js/init.js 和 模块名/js/biz/xxx => 模块名/js/biz.js，然后打包各子模块的对应文件。如果不包含子模块，-childModList 填 null 即可。

2. 图标字体检测 (-checkiconfont)

扫描项目中 JS 和 gspx 文件内所有 aicon-*、bicon-* 图标的使用情况，并上报到文档服务器。

必填参数： | 参数 | 说明 | |------|------| | -webPath | 项目路径 |

可选参数： | 参数 | 说明 | |------|------| | -modName | 模块名称 | | -reportHost | 报告接收服务地址 | | -ignoreFiles | 忽略的文件列表，逗号分隔 | | -cssFiles | 额外需要扫描的 CSS 文件列表，逗号分隔 |

使用示例：

crabatool -checkiconfont -webPath F:\myproject\www -modName mymod -reportHost http://127.0.0.1:9998 -ignoreFiles biconfont/iconfont.js

3. 检测平台更新标记 (-checkUpdate)

检测服务端是否标记了平台需要更新。如果有更新标记且当前 Git 仓库有推送权限，将自动下载更新并推送 Git。主要用于 Jenkins 自动化流程。

必填参数： | 参数 | 说明 | |------|------| | -webPath | 项目路径 |

可选参数： | 参数 | 说明 | |------|------| | -version | 分支版本，默认为 master |

使用示例：

crabatool -checkUpdate -version master -webPath F:\myproject\www

4. 生成文件哈希清单 (-makeHash)

计算指定文件的 SRI（Subresource Integrity）哈希值，生成 JSON 清单文件。支持本地文件、远程 URL 和目录扫描。

必填参数： | 参数 | 说明 | |------|------| | -outJson | 输出 JSON 文件路径 |

可选参数： | 参数 | 说明 | |------|------| | -files | 文件路径列表，逗号分隔（支持本地路径、HTTP/HTTPS URL、目录路径） | | -exts | 文件扩展名过滤，逗号分隔，如 .js（配合目录扫描使用） | | -webPath | 项目路径（用于生成相对路径 key） | | -modName | 模块名称（作为路径前缀） | | -hashName | 哈希算法名称，默认 sha384 |

使用示例：

# 对指定文件列表生成哈希
crabatool -makeHash -webPath F:\project\www -files F:\project\www\js\a.js,F:\project\www\js\b.js -outJson F:\project\www\js\hash.json

# 对目录下所有 JS 文件生成哈希
crabatool -makeHash -webPath F:\project\www -files F:\project\www\js\ -exts .js -outJson F:\output\hash.json -hashName sha384

# 支持远程 URL
crabatool -makeHash -webPath F:\project\www -files http://example.com/js/lib.js,F:\project\www\js\app.js -outJson F:\output\hash.json

输出格式：

{
  "模块名/js/a.js": "sha384-xxxxbase64xxxx",
  "http://example.com/js/lib.js": "sha384-xxxxbase64xxxx"
}

5. 计算页面路径哈希 (-pageHash)

计算 gspx 页面相对路径的哈希值，用于生成页面的配置 ID 前缀码。

必填参数： | 参数 | 说明 | |------|------| | -pageHash | gspx 页面的相对路径（必须以 .gspx 结尾） |

可选参数： | 参数 | 说明 | |------|------| | -ngp true | 使用 NGP 模式计算哈希（会去掉 jxc/sale 等模块前缀） |

使用示例：

crabatool -pageHash /jxc/recordsheet/report.gspx

# NGP 模式
crabatool -pageHash /jxc/recordsheet/report.gspx -ngp true

6. 自动添加版本号 (-addVersion)

在指定文件中将占位符替换为当前时间戳，用于 Jenkins 自动构建时给产品添加版本号。

必填参数： | 参数 | 说明 | |------|------| | -file | 目标文件路径 | | -exp | 替换表达式。直接文本替换（如 AUTOVERSION），或特殊值 version（替换 version: 'xxx' 格式）、staticVersion（替换 staticVersion = 'xxx' 格式） |

使用示例：

# 替换文件中的 AUTOVERSION 文本为时间戳
crabatool -addVersion -file F:\project\www\index.html -exp AUTOVERSION

index.html 中的配合代码示例：

if (!$app.isLocal()) {
    $craba.addVersion({ name: 'every', version: 'AUTOVERSION' });
}

7. 导出 gspx 页面标题清单 (-exportgspx)

扫描指定目录下所有 gspx 文件，提取 <Page> 标签的 Title 属性，导出到桌面的 exportgspx.txt 文件。

必填参数： | 参数 | 说明 | |------|------| | -webPath | 要扫描的目录路径 |

使用示例：

crabatool -exportgspx -webPath F:\project\srcs

输出文件默认生成到桌面 ~/Desktop/exportgspx.txt。

8. 自动生成节点 ID (-autoId)

自动为 gspx 页面中的 UI 控件节点生成唯一 ID。

必填参数： | 参数 | 说明 | |------|------| | -webPath | 项目路径 |

可选参数： | 参数 | 说明 | |------|------| | -ignoreAutoId | 忽略自动生成 ID 的标签列表，逗号分隔 | | -ignoreFiles | 忽略的文件列表，逗号分隔 |

使用示例：

crabatool -autoId -webPath F:\project\www

也可以在配置文件中设置 autoId: true，启动时自动执行。

9. 更新 crabaTool 自身 (-updateTool)

手动检查并更新 crabaTool 工具到最新版本。

crabatool -updateTool

crabaTool 也支持启动时自动分离式更新检查（带命令行参数启动时触发），可通过配置 enableDetachedUpdate: false 关闭。

10. 上传平台资源 (-upload)

对 Craba 平台源码进行打包压缩（JS/CSS），然后上传到服务端指定分支下。

必填参数： | 参数 | 说明 | |------|------| | -targetPath | 平台源码根路径 |

可选参数： | 参数 | 说明 | |------|------| | -version | 目标分支版本 | | -host | 上传服务地址 | | -hidejspath true | 压缩后不保留原始文件路径注释 | | -Debug true | 调试模式 |

使用示例：

crabatool -upload -version master -targetPath F:\CarpaNET_NEW -host http://127.0.0.1:9998 -hidejspath true

11. 上传/更新 NGP 皮肤图标 (-uploadSkin / -updateSkin)

管理 NGP 项目的皮肤和图标库资源。

必填参数： | 参数 | 说明 | |------|------| | -skinPath | 皮肤资源目录路径 | | -version | 分支版本 |

使用示例：

# 上传皮肤
crabatool -uploadSkin -skinPath F:\project\skins -version master

# 更新皮肤
crabatool -updateSkin -skinPath F:\project\skins -version master

12. 字体库解压部署 (-iconfont)

从指定目录中找到字体库 ZIP 文件，解压并部署到目标目录，同时生成标准化的 iconfont.css。

必填参数： | 参数 | 说明 | |------|------| | -zipPath | 字体库 ZIP 文件所在目录 | | -fontPath | 字体文件部署目标目录 |

可选参数： | 参数 | 说明 | |------|------| | -prefix | CSS 类名前缀，默认 .bicon- | | -fontName | 字体名称，默认 biconfont |

使用示例：

crabatool -iconfont -zipPath F:\project\biconfont -fontPath F:\project\skins\bicon -prefix .bicon- -fontName biconfont

13. 转换 Javadoc 文档 (-convertJavadoc)

将 Javadoc 生成的 HTML 文档转换为 JSON 格式。

参数： | 参数 | 说明 | |------|------| | -targetPath | 包含 HTML 文件的目录（批量转换） | | -filePath | 单个 HTML 文件路径（单文件转换） | | -outPath | 输出路径（JSON 文件） |

使用示例：

# 批量转换目录
crabatool -convertJavadoc -targetPath F:\docs\shell -outPath F:\docs\shell.json

# 转换单个文件
crabatool -convertJavadoc -filePath F:\docs\shell\Entity.html -outPath F:\docs\md

14. 上传 Craba 知识库 (-uploadDocs)

将本地 Craba 知识库文档打包为 ZIP 并上传到指定服务器。

必填参数： | 参数 | 说明 | |------|------| | -docsPath | 要上传的文档路径 |

使用示例：

# 上传文档到服务器
crabatool -uploadDocs -docsPath F:\craba-doc

配置参数完整列表

以下参数既可以在配置文件（craba.js）中设置，也可以通过命令行传入。命令行参数优先级高于配置文件。

| 配置文件参数名 | 命令行参数名 | 类型 | 说明 | |----------------|--------------|------|------| | webPath | -webPath | string | 必填。网站根路径，支持相对路径和绝对路径，路径中用 \\ 或 / | | port | -port | number | 必填（-run 时）。前端服务端口号 | | modName | -modName | string | NGP 项目必填。模块名称 | | childModList | -childModList | array / 逗号分隔字符串 | 子模块列表，用于 init.js 和 biz.js 打包 | | refresh | -refresh | boolean | 是否开启文件变动自动刷新浏览器 | | ignoreCompress | -ignoreCompress | boolean | 是否跳过 JS/CSS 压缩 | | webhooks | -webhooks | string | 钉钉群机器人 Webhook 地址（用于推送检测报告） | | progress | -progress | number | 是否显示进度条（0 为不显示） | | globals | -globals | array / 逗号分隔字符串 | checkjs 功能的全局变量白名单 | | ignoreCheck | -ignoreCheck | array / 逗号分隔字符串 | checkjs 功能需忽略的文件/目录（相对 webPath） | | ignoreFiles | -ignoreFiles | array / 逗号分隔字符串 | 忽略的文件列表 | | ignoreAutoId | -ignoreAutoId | array / 逗号分隔字符串 | autoId 功能忽略的标签 | | autoId | -autoId | boolean | 是否自动生成节点 ID | | version | -version | string | 平台分支版本，默认 master | | branchName | -branchName | string | Git 分支名称 | | host | -host | string | 自定义服务地址 | | reportHost | -reportHost | string | 检测报告接收服务地址 | | aiHost | -aiHost | string | AI 服务地址 | | proxy | -proxy | JSON | 代理转发规则 | | proxySrc | -proxySrc | string | 代理配置文件路径（JSON 文件） | | hidejspath | -hidejspath | boolean | 合并文件时不显示原始文件路径 | | Debug | -Debug | boolean | 开启调试模式 | | checkgspx | -checkgspx | boolean | 是否检查 gspx 文件，默认 true | | checkutf8 | -checkutf8 | boolean | 是否检查 UTF-8 编码 | | clearCache | -clearCache | boolean | 清除缓存 | | noOpen | -noOpen | boolean | 启动服务后不自动打开浏览器 | | notCheckCraba | -notCheckCraba | boolean | 跳过 craba.min.js 存在性检查 | | localLogin | -localLogin | boolean | 使用本地 login.html | | defaultPage | -defaultPage | string | 自定义首页 | | virtualName | -virtualName | string | 虚拟路径名 | | mergeInitAndBiz | -mergeInitAndBiz | boolean | 合并 init.js 和 biz.js | | checkCustomControl | -checkCustomControl | boolean | 检查自定义控件，默认 true | | enableFileWatcher | - | boolean | 是否启用文件监听功能，默认 true | | enableDetachedUpdate | - | boolean | 是否启用分离式自动更新，默认 true |

通过 JS 配置文件使用

除了纯命令行方式，crabatool 还支持通过创建一个 JS 配置文件来管理参数，避免每次在命令行中输入大量参数。这种方式不适合Agent和大模型。

使用步骤

第一步： 在项目中创建一个 craba.js 配置文件，将常用参数写在里面：

var crabaTool = require('crabatool');

var config = {
  // 【必填】网站路径
  webPath: "F:/myproject/web/src/main/resources/static/shell",

  // 【必填】前端服务端口
  port: 3001,

  // 【NGP 必填】模块名称
  modName: "shell",

  // 【可选】开启文件变动自动刷新
  refresh: true,

  // 【可选】子模块列表（用于 init.js 和 biz.js 自动打包）
  childModList: ['recordsheet', 'baseinfo', 'accounting'],

  // 【可选】打包后是否跳过压缩（true 不压缩，false 压缩）
  ignoreCompress: true,

  // 【可选】代理转发规则
  proxy: {
    '/apis/': {
      target: 'http://127.0.0.1:8082',
      changeOrigin: true
    }
  }
};

crabaTool.run(config);

第二步： 通过 node craba.js 加上功能命令来执行：

# 启动本地服务（使用配置文件中的 webPath、port 等参数）
node craba.js -run

# 检测 JS 语法
node craba.js -checkjs

# 打包 init.js 和 biz.js
node craba.js -mergeinitjs

命令行参数覆盖配置文件

命令行传入的参数会覆盖配置文件中的同名参数。例如：

# 虽然配置文件中 webPath 指向 shell 目录，但这里会使用命令行传入的路径
node craba.js -run -webPath E:/other/path

# 覆盖端口号
node craba.js -run -port 8080

适用场景

本地开发：把 webPath、port、modName、proxy 等固定参数写到 craba.js 中，每次只需 node craba.js -run 即可启动
多人协作：将 craba.js 提交到 Git 仓库，团队成员 clone 后直接使用，无需记忆大量参数
Jenkins/CI：配置文件设置基础参数，Jenkins 脚本中通过命令行参数动态覆盖特定值

交互式菜单模式

不带任何参数运行 crabatool（或 node craba.js）时，将进入交互式菜单模式：

---------------------------------------------------------------------------------------------------------
1 启动服务。                         主要包含：自动合并打包init.js和biz.js，查看本地平台的版本
2.1 更新当前项目的craba平台(主分支)，然后启动服务。
2.2 更新当前项目的craba平台(其他分支)，然后启动服务。
3 查询最新平台版本和日期。
4 校验当前项目js和gspx语法。
5 打包当前项目前端所有js。
6 安装或更新IDEA环境。
7 安装或更新vscode环境。
8 新建Craba项目。
9 更新 crabaTool 工具。
0 结束
---------------------------------------------------------------------------------------------------------
请输入对应功能的编号（数字）：

通过输入编号选择功能。其中编号 8 支持创建两种类型的项目：

普通 Craba 纯前端项目
NGP 微前端项目

文件监听与热刷新

启动时热刷新

启动服务时通过 -refresh true 参数开启：

crabatool -run -webPath F:\project\www -port 9090 -refresh true

监听文件类型：.js、.css、.gspx、.html
工作原理：通过 WebSocket 通知浏览器，浏览器在被激活（focus）时才执行刷新
WebSocket 端口：自动分配为 port + 6000

文件监听代码检测

启动服务时默认开启文件监听器（OpenFileWatcher），当 .js 文件发生变动时自动执行：

ESLint 语法检查
文件编码检查
文件大小检查
ES6+ 兼容性检查

独立文件监听器

crabatool 也导出了独立的文件监听 API，可在自定义项目中使用：

var openFileWatcher = require('crabatool/tool/openFileWatcher.js');

const watcher = openFileWatcher.createWatcher({
  watchExtensions: ['.js'],
  debounceDelay: 300,
  verbose: false
});

watcher.start('./src');

代理转发配置

启动本地服务时可配置 API 代理转发，基于 http-proxy-middleware。

命令行方式

crabatool -run -webPath F:\project\www -port 9090 -proxy "{'/apis/':{'target':'http://127.0.0.1:8082','changeOrigin':true}}"

注意：命令行中 JSON 使用单引号包裹 key 和 value，工具会自动转换为双引号解析。

配置文件方式

在 craba.js 配置文件中直接写 JS 对象，更直观：

var config = {
  webPath: "F:/project/www",
  port: 9090,
  proxy: {
    '/apis/': {
      target: 'http://127.0.0.1:8082',
      changeOrigin: true
    },
    '/shell/framework/': {
      target: 'http://127.0.0.1:8339',
      changeOrigin: true,
      logLevel: 'debug'
    }
  }
};

也支持数组格式：

proxy: [
  { context: '/apis/', target: 'http://127.0.0.1:8082', changeOrigin: true }
]

从文件读取代理配置

crabatool -run -webPath F:\project\www -port 9090 -proxySrc F:\config\proxy.json

Jenkins 集成

crabatool 可集成到 Jenkins 实现自动化构建流程，典型用法包括：平台更新、JS 打包、代码语法检测、检测报告推送钉钉。

Jenkins Shell 配置示例

# 进入助手目录
cd /opt/ngp/shell/crabatool/

# 更新助手
npm update crabatool -registry=https://registry.npmjs.org

# 打包 init.js 和 biz.js（必须在 jar 打包前执行）
node craba.js -mergeinitjs -modName shell -childModList baseinfo,recordsheet,accounting -ignoreCompress false -progress 0

# 代码语法检测并推送钉钉
node craba.js -checkjs -webPath /opt/ngp/shell/web/src/main/resources/static/shell -modName shell -ignoreCheck folder1,js/craba.min.js -webhooks https://oapi.dingtalk.com/robot/send?access_token=xxxxx -progress 0

关键参数说明

-progress 0：Jenkins 环境下关闭进度条显示
-webhooks：推送地址，推荐使用钉钉群自定义机器人
-ignoreCheck：忽略检测的目录/文件，逗号分隔，相对 webPath 路径
-globals：全局变量白名单。Shell 中 $ 字符需转义为 \$，如 -globals \$doc,$jq

自动添加版本号

在 Jenkins 构建脚本中添加：

crabatool -addVersion -file /opt/project/www/index.html -exp AUTOVERSION

自动检测并更新平台

crabatool -checkUpdate -version master -webPath /opt/project/www

导出的模块 API

crabatool 作为 npm 包，除了 CLI 工具外还导出了以下模块，可在 Node.js 项目中直接引用：

var crabaTool = require('crabatool');

| 模块 | 说明 | |------|------| | crabaTool.run(config) | 启动工具主入口 | | crabaTool.config | 全局配置对象 | | crabaTool.utils | 工具函数集合 | | crabaTool.server | Express 服务器模块（server.start(options) / server.run(options)） | | crabaTool.stringUtils | 字符串处理工具 | | crabaTool.pager | 分页工具 | | crabaTool.cuid | 唯一 ID 生成器 | | crabaTool.JSONCRUD | JSON 文件增删改查工具 | | crabaTool.DbHelper | 数据库操作助手（MySQL） | | crabaTool.StringBuilder | 字符串拼接工具 | | crabaTool.hashUtils | 哈希计算工具 |

命令使用场景

新手快速开始

# 1. 安装crabatool
npm install crabatool -g --registry http://172.17.0.236:4873/

# 2. 创建项目
mkdir my-app && cd my-app

# 3. 安装框架
crabatool -install -webPath .

# 4. 启动开发
crabatool -run -webPath . -port 8080

日常开发

# 启动开发服务器
crabatool -run -webPath . -port 8080

# 代码检查
crabatool -checkjs -webPath . -modName myapp

# 更新框架
crabatool -update -webPath .

项目构建

# 1. 更新框架
crabatool -update -webPath .

# 2. 合并JS
crabatool -mergeinitjs -webPath . -modName myapp

# 3. 添加版本号
crabatool -addVersion -file www/index.html -exp AUTOVERSION

# 4. 生成hash
crabatool -makeHash -webPath www -files file1.js,file2.js -outJson www/js/hash.json

批处理文件

Windows批处理文件 `run.bat`

@echo off
echo 启动Craba开发服务器...
crabatool -run -webPath F:\my-project -port 8080
pause

Windows批处理文件 `update.bat`

@echo off
echo 更新Craba框架...
crabatool -update -webPath F:\my-project
pause

Linux/Mac脚本文件 `run.sh`

#!/bin/bash
echo "启动Craba开发服务器..."
crabatool -run -webPath /path/to/project -port 8080 -refresh

性能优化

开发环境

使用 -refresh 启用热更新
使用 -ignoreCompress 不压缩代码
避免添加版本号

生产环境

合并所有JS文件
压缩代码
添加版本号
生成hash清单

子模块合并

# 合并多个子模块
crabatool -mergeinitjs -webPath F:\my-project -modName myapp -childModList module1,module2,module3

优势：

减少HTTP请求数量
提升页面加载速度
优化资源管理

团队协作

统一开发环境

团队配置文件

创建 craba-team.js：

var crabaTool = require('crabatool');
var config = {
  webPath: "./www",
  port: 8080,
  modName: "myapp",
  refresh: true,
  ignoreCompress: true
};
crabaTool.run(config);

团队成员使用统一配置：

node craba-team.js

代码规范

代码检查配置

crabatool -checkjs -webPath . -modName myapp -globals app,config,utils -ignoreCheck ueditor,iconfont,math.min.js

版本管理

框架版本管理

# 开发环境：使用主分支
crabatool -install -webPath .

# 测试环境：使用特定版本
crabatool -install -webPath . -version ngp4.7

# 生产环境：使用稳定版本
crabatool -install -webPath . -version ngp5.1

故障排查

常见错误

错误1：端口被占用

Error: listen EADDRINUSE: address already in use :::8080

解决方案：

# 使用其他端口
crabatool -run -webPath . -port 3001

错误2：找不到模块

Error: Cannot find module 'crabatool'

解决方案：

# 重新安装crabatool
npm install crabatool -g

错误3：权限不足

Error: EACCES: permission denied

解决方案：

# 使用管理员权限运行
# Windows：以管理员身份运行命令提示符
# Linux/Mac：使用sudo
sudo npm install crabatool -g

常见问题

1. npm 安装失败或延迟

尝试使用内网仓库：

npm install crabatool -g --registry http://172.17.0.236:4873/

或切换为官方源：

npm install crabatool -g --registry https://registry.npmjs.org

2. 命令行参数和配置文件的优先级

命令行参数优先级高于配置文件中的值。例如：

node craba.js -run -webPath E:/other/path

即使 craba.js 中配置了 webPath，也会使用命令行传入的路径。

3. 全局安装后 crabatool 命令找不到

确保使用管理员权限安装，且 npm 全局目录在系统 PATH 中。

4. webPath 路径格式

支持绝对路径和相对路径（相对于命令行执行目录）
路径中可使用 / 或 \\
应指向 login.html（NGP）或 index.html 所在目录

5. 不同环境如何灵活配置

本地开发：使用配置文件（craba.js）设置默认参数
Jenkins/CI：通过命令行参数动态覆盖配置
多项目共用：创建 .bat / .sh 脚本，通过 -webPath 等参数区分项目

6. 跳过系统信息上报

crabatool --skip-report -run -webPath 项目路径

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

crabatool

目录

环境要求

验证安装

安装

快速上手

5分钟快速体验

常用命令示例

命令行参数总览

通用参数

功能命令

常用功能

1. 安装平台资源 (-install)

2. 启动本地服务 (-run)

4. 更新平台资源 (-update)

5. JS 语法检测 (-checkjs)

6. 安装/更新 IDEA 环境 (-idea)

7. 安装/更新 VSCode 环境 (-vscode)

8. 合并压缩 JS 文件 (-mergejs)

9. 合并压缩 CSS 文件 (-mergecss)

10. 打包资源文件为 JSON (-mergeFiles)

11. 查询craba框架的最新版本 (-crabaVersion)

12. 查看crabatool工具版本 (-v)

13. 更新 Craba 知识库 (-updateDocs)

其他功能

1. 打包 init.js 和 biz.js (-mergeinitjs)

2. 图标字体检测 (-checkiconfont)

3. 检测平台更新标记 (-checkUpdate)

4. 生成文件哈希清单 (-makeHash)

5. 计算页面路径哈希 (-pageHash)

6. 自动添加版本号 (-addVersion)

7. 导出 gspx 页面标题清单 (-exportgspx)

8. 自动生成节点 ID (-autoId)

9. 更新 crabaTool 自身 (-updateTool)

10. 上传平台资源 (-upload)

11. 上传/更新 NGP 皮肤图标 (-uploadSkin / -updateSkin)

12. 字体库解压部署 (-iconfont)

13. 转换 Javadoc 文档 (-convertJavadoc)

14. 上传 Craba 知识库 (-uploadDocs)

配置参数完整列表

通过 JS 配置文件使用

使用步骤

命令行参数覆盖配置文件

适用场景

交互式菜单模式

文件监听与热刷新

启动时热刷新

文件监听代码检测

独立文件监听器

代理转发配置

命令行方式

配置文件方式

从文件读取代理配置

Jenkins 集成

Jenkins Shell 配置示例

关键参数说明

自动添加版本号

自动检测并更新平台

导出的模块 API

命令使用场景

新手快速开始

日常开发

项目构建

批处理文件

Windows批处理文件 run.bat

Windows批处理文件 update.bat

Linux/Mac脚本文件 run.sh

性能优化

开发环境

生产环境

子模块合并

团队协作

统一开发环境

团队配置文件

Windows批处理文件 `run.bat`

Windows批处理文件 `update.bat`

Linux/Mac脚本文件 `run.sh`