xb - 前后端打包构建工具

xb（PyPI: xb-init）是一个基于 uv 又类似 uv 的项目管理工具，专为快速初始化 UV + FastAPI + Vue3 + Electron 桌面应用而生。一条命令拉起完整工程脚手架，开发、构建、版本管理一站式搞定。

核心特性

• 一键初始化完整项目结构（xb init demo）
• UV + FastAPI + Vue3 + Electron 开箱即用
• 自动安装前端和 Electron 依赖（npm install，内置国内镜像源）
• 自动 git init 并提交首个 commit（含 lock 文件）
• 自动生成 AGENTS.md（AI 编码助手协作约定）
• 内置全局亮色/暗色主题切换
• 可选 sudo 免密配置（--sudoers）
• 可选内置终端（--terminal）
• 可选自定义应用图标（--icon）
• 内置开发、构建、版本管理命令
• 自动版本检查与一键升级（xb --upgrade）
• 环境诊断（xb doctor）
• Linux DEB 与 Windows NSIS 安装支持

安装

# 安装 uv（若已有可跳过）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方式一：从 PyPI 安装（推荐）
uv tool install xb-init

# 方式二：从源码安装
git clone -b release_v0 https://github.com/xuebli/xb.git
cd xb
uv sync
uv tool install .

# 验证
xb --help

快速开始

# 创建项目
xb init demo

# 带 sudo 免密配置
xb init demo --sudoers

# 带内置终端
xb init demo --terminal

# 同时启用终端和 sudo 免密配置
xb init demo --terminal --sudoers

# 带自定义图标
xb init demo --icon ~/icons/app.png

cd demo

# 启动开发环境
xb dev

# 查看状态
xb dev status

# 停止
xb dev stop

Windows PowerShell 也可以直接运行生成项目脚本：

Set-Location demo
python .\dev.py start
python .\dev.py status
python .\dev.py stop

使用 --terminal 时，Windows 终端使用 PowerShell + ConPTY，支持上下箭头 命令历史、复制粘贴、Tab 补全和 Ctrl+C；Ubuntu/Debian 使用 bash + Unix PTY。

Electron 二进制镜像通过 ELECTRON_MIRROR 环境变量注入，不向 .npmrc 写 npm 不识别的自定义键。若安装过程被网络中断，生成项目的 electron/prepare.js 会在 npm start 或 npm run build 前自动检查并补装 缺失的 Electron 二进制。

xb init 自动行为：

• 执行 npm install（frontend + electron），生成 package-lock.json
  • 生成的 .npmrc 已配好华为云镜像；electron 约 200MB 二进制也走镜像下载
  • 若安装失败或超时，会打印提示但不中断项目创建，可稍后手动重试
• 执行 git init 并提交首个 commit（包含所有文件和 lock 文件）
• 若检测到 PyPI 有新版 xb，会询问是否先升级再创建项目
• 若系统未安装 git 或未配置 user.name/user.email，打印警告但不阻塞

命令一览

应用图标

# 显式指定图标
xb init demo --icon ./my-icon.png

# 不指定时自动查找以下约定路径：
# ./app-icon.png, ./icon.png, ./<package>.png,
# ./assets/app-icon.png, ./assets/icon.png, ./resources/icon.png

生成的项目结构

demo/
├── pyproject.toml          # Python 依赖（uv 管理）
├── AGENTS.md               # AI 编码助手协作约定
├── README.md               # 项目说明（含三种启动方式详解）
├── .gitignore
├── backend/                # FastAPI 后端
│   ├── main.py             # FastAPI 入口（lifespan / CORS / SPA 兜底）
│   ├── backend_build.py    # PyInstaller 打包脚本
│   ├── api/                # API 路由层
│   └── managers/           # 基础设施单例
├── frontend/               # Vue 3 前端
│   ├── package.json
│   ├── package-lock.json
│   ├── .npmrc              # npm 镜像源（华为云）
│   ├── vite.config.js
│   └── src/
├── electron/               # Electron 主进程
│   ├── package.json
│   ├── package-lock.json
│   ├── .npmrc              # npm + electron 二进制镜像源
│   ├── main.js
│   └── resources/          # icon + Linux DEB hooks
├── version/                # 版本管理（pre-commit hook）
├── configs/                # 配置文件
├── datas/                  # 运行时数据（gitignore）
├── dev.py                  # 开发脚本（Windows/Linux）
├── build.py                # 打包脚本（Windows/Linux）
└── .venv                   # Python 虚拟环境

xb 工具自身结构

xb/
├── cli.py                  # CLI 入口（Click + Rich）
├── __init__.py             # 版本号
├── commands/               # 子命令实现
│   ├── init.py             #   初始化（升级检查、图标、npm install、git init）
│   ├── dev.py              #   开发环境管理
│   ├── build.py            #   构建
│   ├── version.py          #   版本管理
│   ├── doctor.py           #   环境诊断
│   └── upgrade.py          #   升级 xb
├── templates/              # Jinja2 项目模板
│   ├── backend/
│   ├── frontend/
│   ├── electron/
│   ├── configs/
│   ├── scripts/
│   ├── version/
│   └── root/
└── utils/
    ├── template_engine.py  # 模板渲染引擎
    ├── validators.py       # 包名校验
    ├── click_helpers.py    # 中文化 Help 输出
    └── version_check.py    # PyPI 版本检查（24h 缓存）

环境要求

• Python: 3.12+
• Node.js: 16+
• npm: 8+
• uv: 已安装
• OS: Windows 10/11 或 Ubuntu/Debian
• Windows 终端: 使用 --terminal 时自动安装 Windows 专用 pywinpty

Windows 可使用 Python、Node.js、npm 和 uv 的官方安装方式或 winget 安装。 Ubuntu/Debian 可使用系统包管理器或官方安装方式。

使用 xb doctor 可一键检查所有环境依赖。

许可证

MIT