Create a new zhin bot project
npm install create-zhin-app快速创建 Zhin 机器人 workspace 项目的脚手架工具,提供一键创建和配置新项目的能力。
- 🚀 一键创建: 使用标准的 npm create / yarn create / pnpm create 命令
- 📦 Workspace 结构: 自动创建 pnpm workspace,支持插件开发
- 🔧 智能配置: 自动安装 pnpm、项目依赖
- 🎯 交互式配置: 选择运行时、配置格式、数据库类型
- 🗄️ 数据库支持: 支持 SQLite、MySQL、PostgreSQL、MongoDB、Redis
- 🔐 安全配置: 自动生成 HTTP 认证和环境变量管理
- 📊 日志配置: 内置完整的日志等级和清理配置
- 🌐 零安装: 无需全局安装,直接使用
``bashnpm(推荐)
npm create zhin-app my-awesome-bot
$3
`bash
进入项目
cd my-awesome-bot开发模式启动
pnpm dev创建插件
zhin new my-plugin构建插件
pnpm build
`工作原理
create-zhin-app 是独立的项目脚手架工具,它的工作流程如下:1. 启动脚手架: 当你运行
npm create zhin-app 时
2. 检测 pnpm: 自动检测并安装 pnpm(如果未安装)
3. 交互式配置: 询问项目名称、运行时、配置格式
4. HTTP 认证配置: 配置 Web 控制台登录信息
- 默认用户名:当前系统用户名
- 默认密码:随机生成 6 位字符串
5. 数据库配置: 选择数据库类型和连接参数
- SQLite (默认,零配置)
- MySQL、PostgreSQL、MongoDB、Redis
- 自动安装对应的数据库驱动包
6. 创建 Workspace: 生成 pnpm workspace 结构
7. 生成配置文件: 包含数据库、日志等完整配置
8. 生成 .env 文件: 保存 HTTP 认证和数据库连接信息
9. 自动安装依赖: 在项目根目录执行 pnpm install
10. 完成提示: 显示登录信息、数据库配置和下一步操作支持的参数
$3
`bash
交互式创建(推荐)
npm create zhin-app my-bot指定项目名称
npm create zhin-app my-awesome-bot
`交互式配置流程:
1. 📝 输入项目名称
2. ⚙️ 选择运行时(Node.js / Bun)
3. 📄 选择配置格式(TypeScript / JavaScript / YAML / JSON)
4. 🔐 配置 Web 控制台登录信息
- 用户名(默认:当前系统用户名)
- 密码(默认:随机 6 位字符)
5. 🗄️ 配置数据库
- SQLite(推荐,零配置)
- MySQL(主机、端口、用户名、密码、数据库名)
- PostgreSQL(主机、端口、用户名、密码、数据库名)
- MongoDB(连接字符串、数据库名)
- Redis(主机、端口、密码、数据库索引)
$3
`bash
使用默认配置(TypeScript + Node.js + 随机密码)
npm create zhin-app my-bot -y
或
npm create zhin-app my-bot --yes
`$3
| 参数 | 说明 | 默认值 |
|------|------|--------|
|
[project-name] | 项目名称(可选,会提示输入) | my-zhin-bot |
| -y, --yes | 跳过交互,使用默认配置 | false |默认配置(使用
-y 时):
- 配置格式: TypeScript (zhin.config.ts)
- 运行时: Node.js
- 包管理器: pnpm(自动安装)
- 数据库: SQLite (./data/bot.db, WAL 模式)
- HTTP 用户名: 当前系统用户名
- HTTP 密码: 随机生成 6 位字符
- 日志等级: INFO
- 日志清理: 7 天,10000 条记录使用场景
$3
`bash
使用默认配置快速创建
npm create zhin-app quick-prototype -y
cd quick-prototype
npm run dev
`$3
`bash
使用 TypeScript + pnpm + node 的生产配置
npm create zhin-app production-bot -- -c ts -p pnpm -r node
`$3
`bash
为团队创建标准化项目
npm create zhin-app team-bot -- \
--config ts \
--package-manager pnpm \
--runtime node \
--yes
`$3
`bash
使用最新技术栈
npm create zhin-app experimental-bot -- -c ts -r node -y
`生成的项目结构
执行
create-zhin-app 后会生成 pnpm workspace 项目结构:`
my-awesome-bot/
├── src/ # 应用源代码
│ ├── index.ts # 主入口文件
│ └── plugins/ # 本地插件目录
│ └── example.ts # 示例插件
├── client/ # 客户端页面
│ └── index.tsx # 示例页面
├── data/ # 数据存储目录
├── plugins/ # 插件开发目录(独立包)
│ └── .gitkeep
├── zhin.config.ts # 配置文件
├── package.json # 根 package.json(包含依赖和脚本)
├── tsconfig.json # TypeScript 根配置
├── pnpm-workspace.yaml # workspace 配置
├── .gitignore # Git 忽略规则
├── .env # 环境变量(包含 HTTP 认证信息)
├── .env.example # 环境变量模板
└── README.md # 项目说明文档
`⚠️ 重要:
.env 文件包含敏感信息(登录密码),已自动添加到 .gitignore,不会被提交到版本控制。Workspace 配置 (
pnpm-workspace.yaml):
`yaml
packages:
- '.' # 根目录即为主应用
- 'plugins/*' # plugins 下的所有插件包
`根 package.json 脚本:
`json
{
"scripts": {
"dev": "zhin dev", // 开发模式
"start": "zhin start", // 生产启动
"daemon": "zhin start --daemon", // 后台运行
"stop": "zhin stop", // 停止服务
"build": "pnpm --filter \"./plugins/*\" build" // 构建所有插件
}
}
`配置文件格式
$3
`javascript
// zhin.config.ts
import { defineConfig } from 'zhin.js';export default defineConfig(async (env) => {
return {
bots: [
{
context: 'process',
name:
${process.pid},
}
],
plugin_dirs: ['./src/plugins', 'node_modules'],
plugins: ['process', 'test-plugin'],
debug: env.DEBUG === 'true'
};
});
`$3
`typescript
// zhin.config.ts
import { defineConfig } from 'zhin.js';
import type { AppConfig } from 'zhin.js';export default defineConfig(async (env) => {
return {
bots: [
{
context: 'process',
name:
${process.pid},
}
],
plugin_dirs: ['./src/plugins', 'node_modules', 'node_modules/@zhin.js'],
plugins: [
'adapter-process',
'http',
'console',
'example'
],
http: {
port: 8086,
username: process.env.HTTP_USERNAME || 'admin',
password: process.env.HTTP_PASSWORD || '123456',
base: '/api'
},
debug: process.env.NODE_ENV === 'development'
};
});
`完整工作流
项目创建完成后,可以执行以下操作:
$3
`bash
cd my-awesome-bot
`$3
`bash
pnpm dev
`访问
http://localhost:8086 查看 Web 控制台登录信息:
- 用户名和密码在创建项目时已配置
- 保存在
.env 文件中
- 创建完成时会在终端显示> 💡 修改密码: 编辑
.env 文件中的 HTTP_USERNAME 和 HTTP_PASSWORD$3
`bash
创建新插件(自动添加到依赖)
zhin new my-awesome-plugin插件会创建在 plugins/my-awesome-plugin/
自动添加到根 package.json 的 dependencies
`$3
`bash
编辑插件文件
plugins/my-awesome-plugin/app/index.ts # 插件逻辑
plugins/my-awesome-plugin/client/ # 客户端页面
保存后自动热重载 ⚡
`$3
`bash
构建所有插件
pnpm build或只构建特定插件
zhin build my-awesome-plugin
`$3
编辑
zhin.config.ts:`typescript
export default defineConfig({
plugins: [
'adapter-process',
'http',
'console',
'example', // 内置示例
'my-awesome-plugin' // 你的插件
]
});
`$3
`bash
确保插件已构建
pnpm build生产启动
pnpm start或后台运行
pnpm daemon停止服务
pnpm stop
`错误处理
$3
1. 网络连接问题
`bash
# 使用国内镜像
npm config set registry https://registry.npmmirror.com
npm create zhin-app my-bot
`2. 权限问题
`bash
# macOS/Linux
sudo chown -R $USER ~/.npm
# Windows (以管理员身份运行)
npm create zhin-app my-bot
`3. Node.js 版本问题
`bash
# 检查 Node.js 版本(需要 >= 18.0.0)
node --version
# 升级 Node.js
# 使用 nvm 或从官网下载最新版本
`环境要求
- Node.js: >= 18.0.0
- npm: >= 8.0.0 (或对应版本的 yarn/pnpm)
- 操作系统: Windows 10+, macOS 10.15+, Linux (现代发行版)
与其他工具对比
| 特性 | create-zhin-app | create-react-app | create-vue |
|------|-------------|------------------|------------|
| 零配置创建 | ✅ | ✅ | ✅ |
| 多配置格式 | ✅ | ❌ | ✅ |
| 多运行时支持 | ✅ | ❌ | ❌ |
| 机器人框架 | ✅ | ❌ | ❌ |
| 热重载开发 | ✅ | ✅ | ✅ |
高级用法
$3
虽然
create-zhin-app 主要调用 CLI 工具,但你可以通过环境变量自定义行为:`bash
设置自定义模板路径
ZHIN_TEMPLATE_DIR=/path/to/custom/template npm create zhin-app my-bot
`$3
`bash
#!/bin/bash
批量创建多个项目
for name in bot1 bot2 bot3; do
npm create zhin-app $name -- -y
done
`$3
`yaml
GitHub Actions 示例
- name: create zhin-app Bot Project
run: |
npm create zhin-app test-bot -- --yes
cd test-bot
npm run build
npm run test
`故障排查
$3
`bash
启用详细日志
DEBUG=create-zhin-app npm create zhin-app my-bot检查参数传递
npm create zhin-app my-bot -- --help
`$3
`bash
清理 npm 缓存
npm cache clean --force删除 node_modules 重新安装
rm -rf node_modules package-lock.json
npm install
`贡献指南
create-zhin-app` 是开源项目,欢迎贡献:1. Fork 项目
2. 创建特性分支
3. 提交更改
4. 创建 Pull Request
MIT License