create-uniboot 使用指南 ​

create-uniboot 是 Uniboot 前端项目脚手架，用于从内网 Nexus 拉取模板并创建业务项目。当前提供三类模板：

模板适用场景
simple简单前端项目，保留基础布局、路由、请求、UI 组件接入
auth复杂中后台项目，含授统一认证授权服务中心（Auth Service）和管理后台服务（Admin Service）等能力
websiteNuxt 4 官网模板（SSR + Uniboot UI + Vite 8），适合官网、产品站、营销页等场景

环境要求 ​

  • Node.js：>= 20.12.0
  • pnpm：>= 11.0.0
  • 可访问内网 Nexus：https://nexus.in.whatspos.cn

建议先确认 pnpm 版本：

bash
pnpm -v

配置内网私服 ​

create-uniboot 发布在内网 Nexus。使用前建议在用户目录配置 ~/.npmrc：

ini
registry=https://nexus.in.whatspos.cn/repository/pax-npm-group/
@uniboot:registry=https://nexus.in.whatspos.cn/repository/pax-npm-release/

如果私服需要登录，执行：

bash
npm login --registry=https://nexus.in.whatspos.cn/repository/pax-npm-release/

也可以使用 token 方式配置到 ~/.npmrc：

ini
//nexus.in.whatspos.cn/repository/pax-npm-release/:_authToken=你的token
always-auth=true

不要把 token 提交到项目仓库。

验证包是否可访问 ​

先确认当前 pnpm 使用的 registry：

bash
pnpm config get registry

如果输出仍是 https://registry.npmmirror.com/ 或公网 npm 地址，说明本机配置还没有切到内网 Nexus。

验证 create-uniboot 是否能从私服查询到：

bash
pnpm view create-uniboot

如果不想修改全局配置，也可以临时指定 registry：

bash
NPM_CONFIG_REGISTRY=https://nexus.in.whatspos.cn/repository/pax-npm-group/ pnpm view create-uniboot

注意

不要使用 pnpm create uniboot my-app --registry=... 或 pnpm --registry=... create uniboot my-app 来临时切换 registry。部分 pnpm 版本的 create 子命令不接受 --registry，会出现 Unknown option: 'registry'，或者仍然从原 registry 拉包。

推荐方式：pnpm create ​

配置好 ~/.npmrc 后，直接执行：

bash
pnpm create uniboot my-app

pnpm create uniboot 会自动解析并下载 create-uniboot 包，然后进入交互式创建流程。

按提示选择模板：

text
simple  - 简单前端项目
auth    - 含授统一认证授权服务中心（Auth Service）和管理后台服务（Admin Service）
website - Nuxt 4 官网模板（SSR + Uniboot UI + Vite 8）

也可以直接指定模板：

bash
pnpm create uniboot my-app --template simple
pnpm create uniboot my-app --template auth
pnpm create uniboot my-app --template website

创建完成后：

bash
cd my-app
pnpm install
pnpm dev

simple 与 auth 基于 Vite，默认开发端口为 3002（可通过 VITE_PORT 配置）。

website 基于 Nuxt 4，默认开发端口为 3000。首次启动前建议复制环境变量并初始化数据库：

bash
cp .env.example .env
# 编辑 .env，至少设置 BETTER_AUTH_SECRET（至少 32 位随机字符串）
pnpm db:push
pnpm db:seed
pnpm dev

website 模板内置官网首页、联系表单、登录页与后台管理示例，认证基于 better-auth，数据层使用 Drizzle + SQLite。联系表单邮件通知需配置 .env 中的 SMTP 相关变量，未配置时仅保存留言。

临时指定 registry ​

如果不方便修改 ~/.npmrc，可以用环境变量只影响当前命令：

bash
NPM_CONFIG_REGISTRY=https://nexus.in.whatspos.cn/repository/pax-npm-group/ pnpm create uniboot my-app

指定模板：

bash
NPM_CONFIG_REGISTRY=https://nexus.in.whatspos.cn/repository/pax-npm-group/ pnpm create uniboot my-app --template auth
NPM_CONFIG_REGISTRY=https://nexus.in.whatspos.cn/repository/pax-npm-group/ pnpm create uniboot my-app --template website

使用 pnpm dlx ​

pnpm dlx 会临时下载并执行 create-uniboot，适合不想全局安装 CLI 的场景：

bash
pnpm dlx create-uniboot my-app

临时指定 registry：

bash
NPM_CONFIG_REGISTRY=https://nexus.in.whatspos.cn/repository/pax-npm-group/ pnpm dlx create-uniboot my-app

全局安装后使用 ​

如果经常创建项目，可以全局安装：

bash
pnpm add -g create-uniboot

然后执行：

bash
create-uniboot my-app
create-uniboot my-app --template simple
create-uniboot my-app --template auth
create-uniboot my-app --template website

检查命令是否可用：

bash
create-uniboot --help

如果提示找不到命令，通常是 pnpm 全局 bin 目录未加入 PATH，可先执行：

bash
pnpm setup

常见问题 ​

仍然从 npmmirror 或公网 npm 拉包 ​

检查：

bash
pnpm config get registry
cat ~/.npmrc

确保 registry 指向：

text
https://nexus.in.whatspos.cn/repository/pax-npm-group/

查询 create-uniboot 返回 404 ​

可能原因：

  • create-uniboot 尚未发布到 Nexus
  • 当前账号没有权限访问私服
  • pax-npm-group 没有包含发布用的 pax-npm-release
  • 本机 registry 仍指向其他源

可以分别检查 group 与 release：

bash
NPM_CONFIG_REGISTRY=https://nexus.in.whatspos.cn/repository/pax-npm-group/ pnpm view create-uniboot
NPM_CONFIG_REGISTRY=https://nexus.in.whatspos.cn/repository/pax-npm-release/ pnpm view create-uniboot

目标目录非空 ​

CLI 会拒绝写入非空目录。请换一个目录名，或先清空目标目录后再执行。

下一步：配置 了解环境变量与项目配置；路由和菜单 了解路由、权限与布局组织方式。