cube-init

初始化一个新的前端项目，使用 @newlifex/cube-vue 框架。当用户说"初始化项目"、"创建新项目"、"搭建前端项目"、"使用 @newlifex/cube-vue 初始化"时使用此技能。自动配置布局、状态管理(Pinia)、路由、API请求库、多语言支持、容器化部署等核心功能，开箱即用。

跳到安装

仓库: NewLifeX/NewLife.Cube
最近来源活动: 2026年7月9日 16:01
检测到的 SKILL.md 语言: 中文
星标: 631
分支: 167

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

直接命令不会经过审查 Prompt；运行前请先检查来源。

npx skills add https://github.com/NewLifeX/NewLife.Cube --skill cube-init

命令会保持在同一行。复制前请横向滚动并检查完整内容。

想先保存到本地？可下载 SkillsMP 当前能够提供的文件。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

SKILL.md

来源说明 · 只读预览

返回搜索返回安装

vue-component-visual-loop

Vue 组件开发的「视觉快速迭代闭环」：Gallery 手动预览（?story= 深链 / 无参数侧栏，带 HMR）+ Vitest 逻辑回归 + Playwright CT 像素级截图。提供手动浏览器预览与 CT 测试编写规范，让"改代码→截图→调整→再截图"在分钟级闭环中完成。

2026-08-10

cube-lov

LOV（List of Values）值集系统使用指南。涵盖后端配置、前端组件、API 封装、枚举自动注册全链路。当用户说"配置值集"、"使用LovSelect"、"添加LOV"、"值集选择"、"枚举下拉"、"使用LOV"时使用。

2026-08-03

cube-add-page

根据后端 NewLife.Cube 控制器定义，在前端项目创建页面组件。当用户说"新增页面"、"创建页面"、"添加功能页面"、"给 XX 模块加页面"时使用。

2026-08-02

查看这个仓库的全部 Skills

name	cube-init
description	初始化一个新的前端项目，使用 @newlifex/cube-vue 框架。当用户说"初始化项目"、"创建新项目"、"搭建前端项目"、"使用 @newlifex/cube-vue 初始化"时使用此技能。自动配置布局、状态管理(Pinia)、路由、API请求库、多语言支持、容器化部署等核心功能，开箱即用。

@newlifex/cube-vue 项目初始化

什么时候用

当用户需要创建一个新的前端项目，或在现有项目中引入 @newlifex/cube-vue 框架时使用。

架构说明

@newlifex/cube-vue 包发布名为 @newlifex/cube-vue，代码中 import 使用 @newlifex/cube-vue/... 路径（通过 pnpm 别名机制）。

支持两种项目结构：

场景	说明	参考
Monorepo 工作空间	项目放在 @newlifex/cube-vue 所在仓库内，通过 workspace 协议引用
独立应用	@newlifex/cube-vue 作为 npm 包安装	后续 npm 发布后

本技能以 monorepo 场景为主，独立应用场景仅调整依赖声明方式（npm install @newlifex/cube-vue + 别名）。

初始化步骤

1. 检查环境

Node.js >= 24
pnpm >= 9
根目录需配置 pnpm-workspace.yaml（monorepo 场景）

2. 注册 workspace（monorepo 场景）

在根目录 pnpm-workspace.yaml 中添加新项目：

packages:
  - '新项目目录'
  - 'Cube/NewLife.Cube.Vue/web'  # 如已有则跳过

3. 创建项目入口文件

在项目 src/ 目录下创建 main.ts：

// src/main.ts
import { initApp } from '@newlifex/cube-vue/core/initApp';
import '@newlifex/cube-vue/core/global.css';

initApp();

4. 创建 index.html

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>应用名称</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

5. 创建配置文件

在项目根目录创建 configs/ 目录：

configs/config.ts - 通用配置：

import type { EnvConfig } from '@newlifex/cube-vue/core/configure/types';

export const config: EnvConfig = {
  base: {
    title: '应用名称',
    footer: '版权所有 © 2026',
  },
  ui: {
    theme: {
      primaryColor: '#1890ff',
    },
  },
  auth: {
    oauthUrl: '/login',
    getUserInfoAxiosConfig: {
      url: '/Admin/User/Info',
      method: 'GET',
    },
  },
};

configs/config.development.ts - 开发环境配置：

import type { EnvConfig } from '@newlifex/cube-vue/core/configure/types';

export const config: EnvConfig = {
  request: {
    baseUrl: import.meta.env.VITE_APP_BASE_API || 'http://localhost:5000',
    timeout: 30000,
  },
};

configs/config.test.ts - 测试环境配置：

import type { EnvConfig } from '@newlifex/cube-vue/core/configure/types';

export const config: EnvConfig = {
  request: {
    baseUrl: import.meta.env.VITE_APP_BASE_API || '/api',
    timeout: 30000,
  },
};

configs/config.production.ts - 生产环境配置（支持容器部署替换）：

import type { EnvConfig } from '@newlifex/cube-vue/core/configure/types';

export const config: EnvConfig = {
  request: {
    baseUrl: '${BUILD_REQUEST_BASE_URL}',
    timeout: 30000,
  },
};

configs/microAppConfig.json - 微应用配置（空数组即可）：

[]

6. 创建环境变量文件

.env - 通用环境变量：

VITE_APP_TITLE=应用名称

.env.development - 开发环境变量：

VITE_APP_ENV=development
VITE_APP_TITLE=应用名称 - 开发环境
VITE_APP_BASE_API=http://localhost:5000

.env.test - 测试环境变量（需 vite --mode test）：

VITE_APP_ENV=test
VITE_APP_TITLE=应用名称 - 测试环境
VITE_APP_BASE_API=http://test-api.example.com

.env.production - 生产环境变量：

VITE_APP_ENV=production
VITE_APP_TITLE=应用名称
# 生产环境 API URL 由容器部署时通过 BUILD_REQUEST_BASE_URL 注入
VITE_APP_BASE_API=/api

7. 配置 Vite

vite.config.ts（monorepo 场景——不需要 alias）：

import { fileURLToPath, URL } from 'node:url';
import { defineConfig, loadEnv } from 'vite';
import vue from '@vitejs/plugin-vue';
import vueJsx from '@vitejs/plugin-vue-jsx';
import cubeFront from '@newlifex/cube-vue/core/plugin';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');

  return {
    plugins: [
      vue(),
      vueJsx(),
      cubeFront(),
    ],
    resolve: {
      alias: {
        '@': fileURLToPath(new URL('./src', import.meta.url)),
        // ❌ 不需要 '@newlifex/cube-vue' 别名——pnpm workspace 协议自动处理
      },
    },
    server: {
      port: 5188,
      host: '0.0.0.0',
      proxy: {
        '/api': {
          target: env.VITE_APP_BASE_API || ,
          : ,
        },
      },
    },
    : {
      : ,
      : ,
      : ,
    },
  };
});

为什么不需要 @newlifex/cube-vue 别名？ 因为 pnpm workspace 协议（workspace:*）+ 别名（"@newlifex/cube-vue": "workspace:@newlifex/cube-vue@*"）会自动创建 node_modules/@newlifex/cube-vue 的 symlink，Node.js 模块解析就能直接找到。

8. 配置 TypeScript

⚠️ 重要：必须添加 @newlifex/cube-vue/core/client 类型声明，否则 initApp() 等 API 会报类型错误。

tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve"

说明："types": ["@newlifex/cube-vue/core/client"] 会自动加载框架的类型声明文件，确保 initApp()、useUserStore() 等 API 的类型提示正常工作。

tsconfig.node.json：

{
  "compilerOptions": {
    "composite": true,
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "strict": true
  },
  "include": ["vite.config.ts"]
}

9. 配置 package.json

Monorepo 场景 — 依赖声明：

使用一条 workspace 依赖：

{
  "dependencies": {
    "@newlifex/cube-vue": "workspace:*",
    "dayjs": "^1.11.0"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.2.0",
    "@vitejs/plugin-vue-jsx": "^4.1.0",
    "cross-env": "^7.0.3",
    "typescript": "~5.8.0",
    "vite": "^6.2.0",
    "vue-tsc": "^2.2.0"
  }
}

条目解释：

依赖	作用
`"@newlifex/cube-vue": "workspace:*"`	正式包名，monorepo 内通过 workspace 协议引用本地库
vue/pinia/element-plus/vue-router	不必须声明（pnpm auto-install-peers 自动装），但建议显式锁定版本

为什么不需要@newlifex/cube-vue: "link:../../@newlifex/cube-vue"？因为 monorepo workspace 模式下，workspace:* 等价且语义更清晰，link: 路径已被淘汰。

10. package.json 完整示例

{
  "name": "your-app",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "dev:test": "vite --mode test",
    "build": "vite build",
    "build:test": "vite build --mode test",
    "preview": "vite preview",
    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs --fix"
  },
  "dependencies": {
    "@newlifex/cube-vue": "workspace:@newlifex/cube-vue@*",
    "@newlifex/cube-vue": "workspace:*",

11. 创建 Docker 配置

在项目根目录创建 docker/ 目录：

docker/Dockerfile：

# 构建阶段
FROM node:20-alpine AS builder

WORKDIR /app

# 安装 pnpm
RUN npm install -g pnpm

# 安装依赖（monorepo 场景需复制根目录 lock）
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

# 复制源代码
COPY . .

# 构建
RUN pnpm run build

# 生产阶段
FROM nginx:alpine

COPY --from=builder /app/dist /usr/share/nginx/html
COPY docker/enterpoint.sh /docker-entrypoint.d/enterpoint.sh
RUN chmod +x /docker-entrypoint.d/enterpoint.sh

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

docker/enterpoint.sh：

#!/bin/bash
set +e
set -x

echo "🚀 Frontend Container Starting..."

# 替换 BUILD_ 开头的占位符
sed -i "s|BUILD_REQUEST_BASE_URL|${BUILD_REQUEST_BASE_URL:-/}|g" /usr/share/nginx/html/index.html

echo "✅ 配置完成"
echo "🎉 启动 Nginx..."

exec "$@"

配置优先级（从低到高）

defaultConfig → configs/config.ts → configs/config.{env}.ts → window._CUBE_CONFIG_ → BUILD_ 占位符

BUILD_ 占位符机制

用于生产环境容器部署时动态注入配置：

在 configs/config.production.ts 中使用 baseUrl: '${BUILD_REQUEST_BASE_URL}'
Vite 构建时会自动将 BUILD_XXX 占位符注入到 dist/index.html
容器启动时，docker/enterpoint.sh 通过 sed 替换占位符

生成的 html 内联脚本格式：

<script>
let cubeConfig = window._CUBE_CONFIG_ || (window._CUBE_CONFIG_={});
let request = cubeConfig["request"] || (cubeConfig["request"]={});
request["baseUrl"] = "BUILD_REQUEST_BASE_URL";
</script>

框架提供的能力

功能	说明	如何使用
布局系统	MainLayout 主布局，侧边栏+内容区	通过 `LayoutKey` 依赖注入自定义
状态管理	UserStore 用户状态，MenuStore 菜单状态	`useUserStore()`, `useMenuStore()`
路由系统	动态路由，微前端支持	通过后端菜单动态生成
API请求	带 Token、401处理、错误提示的 Axios 封装	`import request from '@newlifex/cube-vue/core/utils/request'`
国际化	Vue I18n，支持动态切换	`intl.get('key').d('默认值')`
页面覆盖	Section 机制，可覆盖框架组件	在 `views/` 下创建大写开头的 Vue 文件
BUILD_ 配置注入	生产构建时自动注入到 html	在 config.production.ts 使用 `${BUILD_XXX}`

验证初始化成功

开发环境验证：
- pnpm dev 启动
- 访问 http://localhost:3000
- 检查登录页面正常渲染
生产构建验证：
- pnpm build 成功
- 检查 dist/index.html 是否包含 BUILD_ 占位符脚本

多语言配置（可选）

默认中文，如需多语言在 src/i18n/ 下配置：

src/i18n/index.ts - I18n 实例
src/i18n/locales/ - 语言文件目录

cube-init

来源信息

安装方式

检查来源文件

同仓库更多 Skills

同仓库更多 Skills

@newlifex/cube-vue 项目初始化

什么时候用

架构说明

初始化步骤

1. 检查环境

2. 注册 workspace（monorepo 场景）

3. 创建项目入口文件

4. 创建 index.html

5. 创建配置文件

6. 创建环境变量文件

7. 配置 Vite

8. 配置 TypeScript

9. 配置 package.json

10. package.json 完整示例

11. 创建 Docker 配置

配置优先级（从低到高）

BUILD_ 占位符机制

框架提供的能力

验证初始化成功

多语言配置（可选）

@newlifex/cube-vue 项目初始化

什么时候用

架构说明

初始化步骤

1. 检查环境

2. 注册 workspace（monorepo 场景）

3. 创建项目入口文件

4. 创建 index.html

5. 创建配置文件

6. 创建环境变量文件

7. 配置 Vite

8. 配置 TypeScript

9. 配置 package.json

10. package.json 完整示例

11. 创建 Docker 配置

配置优先级（从低到高）

BUILD_ 占位符机制

框架提供的能力

验证初始化成功

多语言配置（可选）