@neuxnet/neux-cli

v0.2.12

Published

3 days ago

Standalone CLI and Node API for Neux mini program build, pack, preview, and CI automation.

0High
0Medium
0Low

zhaoyanhui

neuxnet_org

shentengfly

miniapp cli ci preview

Neux CLI 中文文档

Neux CLI 是面向小程序项目的独立命令行工具，覆盖本地开发、.wgt 交付包构建、调试预览、上传、提审、状态查询，以及未来 IDE Node 侧集成。

快速开始

npm 公仓全局安装

Neux CLI 已发布到 npm 公仓的 @neuxnet scope 下。如果本机 .npmrc 曾经把 @neuxnet scope 指向私仓，安装时需要显式覆盖为 npm 公仓：

全局安装：

npm install -g @neuxnet/neux-cli --registry=https://registry.npmjs.org/
neux --version
neux --help

升级到 npm 公仓最新版本：

npm install -g @neuxnet/neux-cli@latest --registry=https://registry.npmjs.org/

如果本机配置中的 @neuxnet:registry 仍然覆盖命令行参数，请临时移除该配置，或使用单独的 npm user config，并将其 registry 设置为 https://registry.npmjs.org/。

创建一个新小程序：

npx @neuxnet/neux-cli init my-miniapp --app-id touristappid --name "My Miniapp"
cd my-miniapp

在已有小程序项目中安装 CLI：

npm install -D @neuxnet/neux-cli

推荐在小程序项目的 package.json 中保留短命令：

{
  "scripts": {
    "build": "neux build",
    "dev": "neux dev",
    "upload": "neux upload --preview",
    "debug": "neux debug",
    "submit": "neux submit"
  }
}

初始化项目时会把当前正在执行的 CLI 作为项目级 devDependency 写入 package.json。这是为了让 npm run dev/build/debug/... 优先从项目自己的 node_modules/.bin 解析 neux，从而让本机开发者、协作者和 CI 使用项目声明的同一版本范围，而不是依赖每台机器上未受项目管理的全局 CLI。提交初始化后生成的 lockfile 可以进一步锁定精确版本。版本号由 neux init 从当前 CLI 包的 package.json 动态读取，不再硬编码旧版本。

这个依赖从“能否执行命令”的角度不是绝对必要：如果始终全局安装 CLI，脚本也可能运行。但不声明项目级依赖就无法保证不同机器和 CI 使用相同版本，容易出现编译、构建或上传行为不一致。因此推荐保留。若只想使用全局 CLI，可以删除该 devDependency，但同时应自行确保所有环境的 CLI 版本一致。

常用命令：

npx @neuxnet/neux-cli init my-miniapp
npm run dev
npm run build
npm run debug
npm run upload
npm run submit

使用 npm 包

小程序的运行时 npm 依赖放在小程序根目录 package.json 的 dependencies 中。先安装依赖，再执行 neux npm 将依赖构建到 miniprogram_npm：

npm install dayjs
neux npm
neux build

neux npm 支持微信小程序 npm 包（miniprogram 或 miniprogram_dist）以及普通 JavaScript npm 包，并会递归处理 dependencies。需要先执行 npm install；动态 require 不受支持。

检查 npm 构建产物但不修改文件：

neux npm --check

检查只比较已声明依赖、已安装版本和生成产物的包元数据，不比较文件内容，因此不会因为开发者手动调整 miniprogram_npm 中的代码而报错。如果检查发现产物缺失或版本不一致，会提示重新执行 neux npm。

例如使用公开的小程序组件包：

npm install @vant/weapp
neux npm

页面配置组件路径时使用构建后的 miniprogram_npm 路径：

{
  "usingComponents": {
    "van-button": "@vant/weapp/button/index"
  }
}

当前不保证支持依赖 Node.js 内置模块（例如 fs、path）、浏览器 DOM 或动态加载文件的 npm 包。neux npm 会覆盖旧的 miniprogram_npm 目录，请将该目录视为构建产物。

neux build 和 neux dev 不会自动重建或覆盖 miniprogram_npm。构建时只会进行只读检查；如果已安装依赖与生成元数据不一致，会提示执行 neux npm。

npm run build 会编译小程序并在项目内生成 dist/release/<appId>.wgt。.wgt 是当前唯一交付物。

npm run dev 启动的 H5 开发服务会在同一端口提供 /proxy。小程序中的 wx.request 在浏览器环境由 Container 转发到该路径，因此不需要每个小程序单独维护代理脚本。代理只用于本地 dev/web，不会进入 .wgt 或宿主运行时。

代理请求体沿用小程序网络 API 的开发适配格式：

{
  "url": "https://api.example.com/path",
  "method": "POST",
  "data": {},
  "header": {}
}

开发服务只允许来自本机的浏览器 Origin，并拒绝私有网段、回环地址和保留地址的目标，避免把开发代理变成任意内网转发器。需要允许额外开发 Origin 时，可设置 DIMINA_PROXY_ALLOWED_ORIGINS，多个 Origin 使用逗号分隔。

常用命令

neux init ./my-miniapp --app-id touristappid --name "My Miniapp"
neux --version
neux cli-version --json
neux inspect --json
neux dev --port 7788
neux build --version 1.0.1 --json
neux config doctor --server-url https://miniapp.example.com --json
neux debug --page-path pages/index/index --query foo=bar
neux upload --preview --changelog "Release notes" --channel test
neux submit --version-id 123 --channel test
neux status --json
neux audit-status --version-id 123 --json

当命令在小程序项目根目录中执行时，--project 默认指向当前目录。

初始化小程序

neux init <dir> 会创建一个可运行的示例小程序，包含计数器、双 Tab 页面和列表渲染示例，同时生成 AI 开发上下文文件：

project.config.json
package.json
app.json
app.js
app.nxss
pages/index/index.json
pages/index/index.js
pages/index/index.nxml
pages/index/index.nxss
AGENTS.md
llms.txt
mcp.example.json

示例：

neux init ./my-miniapp --app-id touristappid --name "My Miniapp"
cd my-miniapp
neux dev
neux build

直接在终端执行 neux init ./my-miniapp 时，CLI 会交互式询问 Project name、App ID、Server URL 和隐藏输入的 CLI Key。Server URL 默认是 https://demo-c.paas.superapp.neuvision.cn，按回车即可使用。App ID 和 Server URL 写入项目；CLI Key 按 App ID 保存到用户级 ~/.neux/config.json，不会写入项目文件或 Git。初始化模板还会生成 AGENTS.md、llms.txt 和 mcp.example.json，其中包含官方 AI 文档、LLM 文本导出、MCP endpoint 和 Agent Skill 入口。目标目录必须不存在或为空；如果需要写入已有目录，可以使用 --force。

初始化项目还会生成 .vscode/neux-json-schemas/ 下的 JSON Schema，并自动注册到 .vscode/settings.json。在 CLI 仓库中执行 npm run verify:schemas 可检查 Schema 资产、初始化注册和源码字段清单是否保持一致。VS Code 可为 app.json、页面 JSON、project.config.json、project.private.config.json 和 neux.config.json 提供字段补全、Hover、枚举值提示和基础校验。页面是否真实存在、组件路径是否有效等跨文件语义检查仍由 CLI/编译器负责。

neux inspect --project ./miniapp --json 还会报告页面文件、TabBar 页面归属和图标资源、分包页面以及本地 usingComponents 路径诊断。存在错误时返回的 ok 为 false，但仍保留项目元数据，便于 IDE 集成展示问题。

初始化项目还会生成 .vscode/neux-components.code-snippets。在 .nxml 文件中输入 nxButton、nxInput 或 nxScrollView 等前缀并确认，即可插入包含源码声明属性和 bind* 事件的组件模板。这是编辑辅助能力，不替代组件级 Language Server 校验。

neux build 默认使用相同的项目级校验；存在配置错误时会在调用编译器前终止。Node API 调用方如需兼容旧的“仅调用编译器”行为，可以显式传入 validate: false。

项目校验器还会检查入口页面声明、TabBar 最多五项、重复或重叠的分包根路径、主包与分包页面重复，以及 miniprogramRoot 是否越出项目目录。这些属于项目级规则，不属于 JSON Schema 能独立完成的校验。

初始化后可以这样运行：

cd my-miniapp
npm install
npm run dev
npm run debug

修改当前项目的 CLI Key：

neux config set

也可以直接传入新 Key：

neux config set --key NEW_CLI_KEY

脚本或 CI 可以使用 --no-interactive，并通过 --app-id、--server-url、--key 传值。--json 也会自动关闭交互。

命令说明

| 命令 | 作用 | | --- | --- | | neux init <dir> | 从 0 创建一个新的小程序项目 | | neux inspect | 读取小程序项目信息 | | neux dev | 编译、打开 H5 容器、监听文件并热更新 | | neux build | 构建客户端 .wgt 交付包，默认输出到 dist/release | | neux upload | 上传 signed service 体验包 | | neux debug | 上传调试预览包，并输出 deeplink 与可扫码终端二维码 | | neux submit | 提交体验版本审核 | | neux status | 查询 signed service 版本信息 | | neux audit-status | 查询审核状态 | | neux config doctor | 诊断 signed service 配置 | | neux config set | 交互式修改当前项目的 CLI Key | | neux update | 检查并更新 CLI | | neux --version | 查看当前安装的 CLI 版本 | | neux cli-version | 查看详细 CLI 包信息，适合 IDE/CI | | neux compile | 仅执行内置小程序编译 | | neux pack | 将已有编译产物打包为本地归档 | | neux wgt | neux build 的兼容别名 |

service-preview 和 audit-status 属于高级服务命令。debug-preview、submit-audit、 meta、version、audit 和 wgt 是兼容命令；preview、web 是旧版本地预览入口。调用兼容命令或旧版命令时，CLI 会向 stderr 输出弃用提示；新脚本优先使用 build、dev、debug、upload、submit、status。可使用 neux <command> --help 查看命令级选项。

更新 CLI

手动检查更新：

neux update --check

检查并更新到 npm registry 上的最新版本：

neux update

未传 --registry 时，neux update 会优先读取当前 npm 配置里的 scope registry，例如 @neuxnet:registry，再回退到默认 registry。

私服 registry：

neux update --registry https://registry.example.com

自动更新默认关闭。需要自动更新时，可以在本次命令开启：

NEUX_CLI_AUTO_UPDATE=1 neux dev

自动更新失败只会输出 warning，不会中断原命令。CI/CD 建议显式执行 neux update --check --json 或固定 CLI 版本，避免构建期间隐式变更工具链。

默认输出目录

| 命令 | 默认输出 | | --- | --- | | neux build | dist/release | | neux wgt | dist/release | | neux compile | dist/build | | neux dev | dist/dev | | neux web | dist/web | | neux pack | dist/pack | | neux preview | dist/preview |

`.wgt` 交付包结构

neux build、neux wgt 和默认 signed service 上传命令都会生成客户端下载所需的 .wgt 文件。

外层 .wgt 是 zip 文件，解压后必须只有两个文件：

config.json
<appId>.zip

内层 <appId>.zip 包含小程序生产/编译输出目录内的文件。CLI 不会直接压缩整个小程序源码目录。

调试预览

neux debug 会先构建 .wgt，再上传调试预览包，并默认直接在终端展示可扫码的二维码：

neux debug

可以指定启动页面和参数：

neux debug \
  --page-path pages/detail/index \
  --query 'id=1' \
  --scene 1001 \
  --launch-from cli \
  --location 31.2,121.5

二维码输出控制：

neux debug --qr-format png --qr-output ./dist/release/preview.png
neux debug --qr-format terminal
neux debug --qr-format none
neux debug --qr-format none --qr-output ./dist/release/preview.qr.txt
neux debug --copy

默认终端二维码使用紧凑的 ANSI 上半块字符，显式设置字符上、下两个模块区域的黑白颜色，并保留 4 个模块静区。一个终端字符承载上下两行二维码模块，视觉比例接近正方形，同时减少终端默认前景色、背景色和行距差异对扫码的影响。PNG 仍可通过 --qr-format png --qr-output <path> 显式生成。

--json 模式不会默认创建图片，适合 CI 和 IDE 集成；如需图片，显式传入 --qr-format png --qr-output <path>：

neux debug --json

上传与提审

上传体验包：

neux upload --preview --changelog "Release notes" --channel test

upload --preview 返回预览信息时，即使服务端 scanUrl 只有 appId 和 appVerType，CLI 也会把本次打包的 versionName 追加为 deeplink 的 version 查询参数。

提交审核：

neux submit --version-id 123 --channel test

查询版本信息：

neux status --json

查询审核状态：

neux audit-status --version-id 123 --json

--changelog 会作为上传变更说明，同时兼容填充 desc。--channel 用于测试通道、灰度通道或后端定义的环境通道。

Signed Service 配置

signed service 使用 appId + key 对机器请求签名。请求头包含：

X-App-Id
X-Timestamp
X-Nonce
X-Signature

配置优先级：

CLI 参数：--server-url、--app-id、--key、--profile
环境变量：NEUX_CLI_SERVER_URL、NEUX_CLI_APP_ID、NEUX_CLI_PROFILE、应用或 profile 专属 key、NEUX_CLI_KEY
项目配置：neux.config.json，或 project.config.json 顶层字段
用户 profile：$NEUX_CLI_CONFIG 或 ~/.neux/config.json

项目配置示例：

{
  "appId": "app_xxx",
  "profile": "demo-private",
  "versionName": "1.2.3",
  "versionCode": 12
}

也可以写在 project.config.json 中：

{
  "appid": "app_xxx",
  "compileType": "miniprogram",
  "miniprogramRoot": "",
  "neuxCli": {
    "serverUrl": "https://demo-c.paas.superapp.neuvision.cn"
  },
  "versionName": "1.2.3",
  "versionCode": 12
}

serverUrl 也可以写在 project.config.json 顶层；模板默认使用 neuxCli.serverUrl，便于和 IDE 项目字段区分。project.private.config.json 可以覆盖本地非敏感配置，例如 appid、projectname、versionName、versionCode、setting、packOptions、neuxCli.serverUrl。

CLI Key 不写入项目配置或 Git，而是按 App ID 保存在用户级 ~/.neux/config.json 的 keys 字段中。需要切换或更新时执行 neux config set；CI 仍建议使用 --key 或环境变量。

多小程序与 CI/CD

推荐为每个小程序注入应用专属 key：

export NEUX_CLI_SERVER_URL=https://miniapp.example.com
export NEUX_CLI_KEY_WXBAF4B47DE04F1D8A=key_xxx
npm run upload

环境变量后缀会把 appId 或 profile 转成大写，并把非字母数字字符替换为 _。

key 解析顺序：

--key
NEUX_CLI_KEY_<APPID_NORMALIZED>
NEUX_CLI_KEY_<PROFILE_NORMALIZED>
NEUX_CLI_KEY
用户级 ~/.neux/config.json 中当前 App ID 对应的 CLI Key

GitHub Actions 示例：

env:
  NEUX_CLI_SERVER_URL: https://miniapp.example.com
  NEUX_CLI_KEY_WXBAF4B47DE04F1D8A: ${{ env.MINIAPP_BASE_KEY }}

steps:
  - run: npm run upload

配置缺失时，可以运行：

neux config doctor --json

诊断输出会显示缺失字段、配置来源、可用 key 环境变量名和 key 是否存在，但不会打印 key 值。

版本号与版本 code

neux build 和 signed service 上传命令按以下顺序读取版本：

CLI 参数：--version-name、--version、--version-code
项目配置：neux.config.json、project.config.json 顶层 versionName / versionCode
package.json 的 version，用于 versionName
默认值：versionName = 1.0.0，versionCode = 1

示例：

neux build --version-name 1.2.3 --version-code 12
neux upload --preview --version 1.2.3

JSON 输出约定

一次性命令在 --json 模式下只向 stdout 写入一个 JSON 对象：

neux build --json
neux upload --preview --json

长时间运行的开发命令会输出 JSON Lines：

neux dev --json
neux preview --json --stay

稳定事件名包括：

build-start
build-success
build-error
ready
reload
close

在 JSON 模式下，编译进度日志会重定向到 stderr，stdout 保持机器可读。

Provider 适配器

默认不传 --provider 时，upload、debug、submit 等命令使用 signed service。默认 signed service 不实现 login；login 不会出现在根命令帮助中，仅在自定义 Provider 实现 login 时才有意义。

如果要测试自定义适配器，可以传入 provider 模块：

neux upload --provider ./provider.mjs --json
neux debug-preview --provider ./provider.mjs --build --json
neux submit --provider ./provider.mjs --json

provider 模块可以导出 createProvider(options)、默认 provider 对象或命名导出 provider：

export function createProvider(options) {
  return {
    async upload({ artifact, project }) {
      return {
        ok: true,
        provider: 'example',
        appId: project.appId,
        packagePath: artifact.packagePath,
      }
    },
  }
}

--provider local-file 可用于 CI smoke test。它只写本地 JSON 记录，不访问远程服务。

Node API

CLI 是 Node API 的薄封装，未来 IDE 可以复用相同生命周期，而不需要解析终端输出。

import {
  buildProject,
  inspectProject,
  packProject,
  startDev,
  startPreview,
  startWeb,
} from '@neuxnet/neux-cli'

const info = await inspectProject({ project: './miniapp' })
const build = await buildProject({ project: './miniapp' })
const pack = await packProject({ project: './miniapp', out: './artifacts' })

const dev = await startDev({ project: './miniapp', port: 0, open: false })
console.log(dev.url)
await dev.close()

长时间运行的 API 支持 onEvent(event)，便于 IDE 消费稳定生命周期事件。

内置编译器

发布后的 CLI 会内置小程序编译器。小程序项目不需要显式安装额外的编译器包。

在仓库内发布前刷新内置 compiler：

pnpm --dir ../fe build
npm run sync:compiler

一键准备发布资源：

npm run prepare:publish

仅在测试自定义 compiler 时使用：

neux build --compiler-module ./mock-compiler.mjs

本地开发与验证

在 neux-cli 包内运行：

npm test
npm run smoke:help
npm run pack:dry

在示例小程序中验证 .wgt：

cd ../fe/example/base
npm run build
unzip -l dist/release/*.wgt

外层 .wgt 应只包含 config.json 和 <appId>.zip。

语言

CLI 默认使用英文。可以通过 --lang zh-CN 或 NEUX_CLI_LANG=zh-CN 切换 CLI 的帮助和终端结果标签：

neux --help --lang zh-CN
NEUX_CLI_LANG=zh-CN neux init ./miniapp

Web 容器默认使用英文。启动 neux dev 时，可以使用 neux dev --lang zh-CN，或者在页面 URL 中添加 ?lang=zh-CN。--json 输出保持稳定的机器可读字段，不随语言改变。