Uniappx Project Creator

When to use this skill

Use this skill whenever the user wants to:

• Create a new uni-app-x project from scratch
• Initialize uni-app-x project structure with TypeScript and Vue 3
• Set up development environment for uni-app-x
• Generate project templates with TypeScript configuration
• Configure manifest.json and pages.json for uni-app-x
• Create uni-app-x pages and components with TypeScript
• Set up uni-app-x project with HBuilderX or CLI

How to use this skill

To create a uni-app-x project with a single command or via HBuilderX:

1. Identify the project type from the user's request:

• Standard uni-app-x project → Use TypeScript + Vue 3 template
• HBuilderX project → Use HBuilderX creation method
• CLI project → Use official CLI commands

2. Load the appropriate example file from the examples/guide/ directory:

• examples/guide/installation.md - Installation and environment setup
• examples/guide/quick-start.md - Quick start guide
• examples/guide/project-types.md - Different project types and templates

3. Load the appropriate template file from the templates/ directory:

• templates/project-templates.md - Project structure templates
• templates/cli-commands.md - CLI command templates

4. Follow the specific instructions in those files for project creation, structure, and configuration

5. Generate the project structure with proper TypeScript and Vue 3 configurations

Important Notes:

• This skill focuses on uni-app-x CLI quickstart and HBuilderX creation flows
• Use one command creation when the user wants "一句话创建"
• uni-app-x requires Vue 3 + TypeScript + Vite

Examples and Templates

Examples

Located in examples/guide/:

• installation.md - Installation guide for uni-app-x development environment
• quick-start.md - Quick start guide for creating first uni-app-x project
• project-types.md - Different project types and configurations

Templates

Located in templates/:

• project-templates.md - Complete project structure templates with TypeScript
• cli-commands.md - CLI command templates for project creation

API Reference

This skill focuses on project creation and initialization. For component and API references, see uniappx-project-guide.

Best Practices

1. Use TypeScript: uni-app-x requires TypeScript, ensure proper type definitions 2. Vue 3 Composition API: Use Composition API with <script setup> syntax 3. Configure properly: Set up manifest.json, pages.json, and tsconfig.json correctly 4. Organize structure: Follow standard uni-app-x directory structure 5. Version control: Initialize git repository after project creation

Resources

• Official Documentation: https://uniapp.dcloud.net.cn/quickstart-cli.html
• uni-app-x Documentation: https://doc.dcloud.net.cn/uni-app-x/
• HBuilderX: https://www.dcloud.io/hbuilderx.html
• TypeScript: https://www.typescriptlang.org/
• Vue 3: https://cn.vuejs.org/

Keywords

uniappx, uni-app-x, project creator, TypeScript, Vue 3, project initialization, HBuilderX, manifest.json, pages.json, uni-app-x setup, uni-app-x template, 创建项目, 项目初始化, 快速开始

能力边界

✅ 适用场景

• 当你需要使用此技能对应的技术栈时
• 当项目需要遵循最佳实践时
• 当需要快速上手或深入理解核心概念时

⚠️ 需要注意

• 复杂业务逻辑需要结合具体场景调整
• 性能优化需要根据实际数据量评估

❌ 不适用场景

• 不相关的技术栈或框架
• 需要完全自定义的特殊场景

常见陷阱 (Gotchas)

1. 版本兼容性：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异 2. 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查 3. 环境变量：确保所有必要的环境变量已正确设置，敏感信息不要硬编码 4. 依赖冲突：多版本共存时注意依赖冲突，使用 lock 文件锁定版本 5. 性能陷阱：大数据量场景下注意性能优化，避免 N+1 查询等常见问题

使用流程

Step 1: 环境准备

确保开发环境已安装必要的依赖和工具。

Step 2: 配置初始化

根据项目需求进行基础配置。

Step 3: 核心功能使用

按照示例代码实现核心功能。

Step 4: 测试验证

运行测试确保功能正常。

Step 5: 部署上线

完成开发后进行部署和监控。

uni-app-x 安装指南

官方文档

参考官方文档：https://uniapp.dcloud.net.cn/quickstart-cli.html

环境要求

HBuilderX 版本

• 最低版本：HBuilderX 3.93+
• 推荐版本：最新版本

Node.js 版本

• 推荐版本：Node.js 16.x 或更高版本
• 最低版本：Node.js 14.x

# 检查 Node.js 版本
node --version

# 检查 npm 版本
npm --version

TypeScript

uni-app-x 使用 TypeScript，需要 TypeScript 支持。

安装方式

方式一：使用 HBuilderX（推荐）

HBuilderX 是 DCloud 官方提供的 IDE，内置 uni-app-x 开发环境。

下载安装： 1. 访问 https://www.dcloud.io/hbuilderx.html 2. 下载 HBuilderX（App 开发版，版本 3.93+） 3. 安装并启动 HBuilderX

创建项目： 1. 文件 → 新建 → 项目 2. 选择 uni-app x 3. 选择模板（默认模板、示例模板等） 4. 填写项目名称和路径 5. 点击创建

方式二：使用 CLI

# 使用官方模板创建项目
npx degit dcloudio/uni-preset-vue-x my-project

# 或使用官方脚手架
npm create uni-app-x@latest my-project

项目结构

创建后的项目结构：

my-project/
├── src/                    # 源代码目录
│   ├── pages/             # 页面目录
│   │   ├── index/
│   │   │   └── index.vue
│   │   └── ...
│   ├── components/        # 组件目录
│   │   └── ...
│   ├── static/            # 静态资源
│   │   └── ...
│   ├── utils/             # 工具函数
│   ├── api/               # API 接口
│   ├── store/             # 状态管理
│   ├── App.vue            # 应用入口
│   └── main.ts            # 入口文件（TypeScript）
├── manifest.json          # 应用配置
├── pages.json             # 页面路由配置
├── vite.config.ts         # Vite 配置
├── tsconfig.json          # TypeScript 配置
└── package.json

配置文件

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "jsx": "preserve",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "types": ["@dcloudio/types"]
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"],
  "exclude": ["node_modules"]
}

vite.config.ts

import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'

export default defineConfig({
  plugins: [uni()],
  server: {
    port: 3000,
    open: true
  }
})

manifest.json

{
  "name": "my-app-x",
  "appid": "",
  "description": "",
  "versionName": "1.0.0",
  "versionCode": "100",
  "uni-app-x": {
    "compilerVersion": "1.0.0",
    "vueVersion": "3",
    "typescript": true
  },
  "app-plus": {
    "usingComponents": true,
    "compilerVersion": 3
  },
  "h5": {
    "router": {
      "mode": "hash",
      "base": "/"
    }
  },
  "mp-weixin": {
    "appid": "",
    "setting": {
      "urlCheck": false
    },
    "usingComponents": true
  }
}

验证安装

创建项目后，验证安装是否成功：

cd my-project
npm install
npm run dev:h5

如果浏览器自动打开并显示 uni-app-x 欢迎页面，说明安装成功。

常见问题

1. HBuilderX 版本过低

确保使用 HBuilderX 3.93 或更高版本。

2. TypeScript 错误

检查 tsconfig.json 配置是否正确，确保安装了 @dcloudio/types。

3. 依赖安装失败

使用国内镜像：

npm config set registry https://registry.npmmirror.com

下一步

安装完成后，参考 quick-start.md 开始创建第一个项目。

uni-app-x 项目类型

官方文档

参考官方文档：https://uniapp.dcloud.net.cn/quickstart-cli.html

项目特点

uni-app-x 项目统一使用：

• Vue 3：必须使用 Vue 3
• TypeScript：必须使用 TypeScript
• Vite：使用 Vite 作为构建工具
• Composition API：推荐使用 Composition API

项目结构

所有 uni-app-x 项目都遵循相同的结构：

my-uniappx-project/
├── src/
│   ├── pages/             # 页面目录
│   ├── components/        # 组件目录
│   ├── static/            # 静态资源
│   ├── utils/             # 工具函数
│   ├── api/               # API 接口
│   ├── store/             # 状态管理
│   ├── App.vue            # 应用入口
│   └── main.ts            # TypeScript 入口
├── manifest.json          # 应用配置
├── pages.json             # 页面路由配置
├── vite.config.ts         # Vite 配置
├── tsconfig.json          # TypeScript 配置
└── package.json

配置文件

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "jsx": "preserve",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "types": ["@dcloudio/types"]
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"],
  "exclude": ["node_modules"]
}

vite.config.ts

import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'

export default defineConfig({
  plugins: [uni()],
  server: {
    port: 3000,
    open: true
  }
})

manifest.json

{
  "name": "my-app-x",
  "appid": "",
  "description": "",
  "versionName": "1.0.0",
  "versionCode": "100",
  "uni-app-x": {
    "compilerVersion": "1.0.0",
    "vueVersion": "3",
    "typescript": true
  },
  "app-plus": {
    "usingComponents": true,
    "compilerVersion": 3
  },
  "h5": {
    "router": {
      "mode": "hash",
      "base": "/"
    }
  },
  "mp-weixin": {
    "appid": "",
    "setting": {
      "urlCheck": false
    },
    "usingComponents": true
  }
}

创建方式

使用 HBuilderX

1. 文件 → 新建 → 项目 2. 选择 uni-app x 3. 选择模板（默认模板、示例模板等） 4. 填写项目信息 5. 点击创建

使用 CLI

# 使用官方模板
npx degit dcloudio/uni-preset-vue-x my-project

# 或使用官方脚手架
npm create uni-app-x@latest my-project

开发规范

1. TypeScript 使用

• 为所有组件和函数添加类型定义
• 使用接口定义数据结构
• 利用类型推断减少冗余代码

2. Composition API

• 使用 <script setup> 语法
• 提取可复用的组合式函数
• 合理组织代码逻辑

3. 代码规范

• 遵循 Vue 3 最佳实践
• 使用 ESLint 和 Prettier
• 统一代码风格

参考资源

• uni-app-x 文档：https://doc.dcloud.net.cn/uni-app-x/
• Vue 3 文档：https://cn.vuejs.org/
• TypeScript 文档：https://www.typescriptlang.org/
• Vite 文档：https://cn.vitejs.dev/

uni-app-x 快速开始

官方文档

参考官方文档：https://uniapp.dcloud.net.cn/quickstart-cli.html

创建第一个项目

一句话创建（CLI）

# 官方脚手架（推荐）
npm create uni-app-x@latest my-uniappx

# 或使用官方模板
npx degit dcloudio/uni-preset-vue-x my-uniappx

使用 HBuilderX

1. 打开 HBuilderX（版本 3.93+） 2. 文件 → 新建 → 项目 3. 选择项目类型：uni-app x 4. 选择模板：默认模板或示例模板 5. 填写项目信息：

• 项目名称：my-first-uniappx
• 项目路径：选择保存位置

6. 点击创建

使用 CLI

# 创建项目
npx degit dcloudio/uni-preset-vue-x my-first-uniappx

# 进入项目目录
cd my-first-uniappx

# 安装依赖
npm install

# 运行到 H5
npm run dev:h5

# 运行到微信小程序
npm run dev:mp-weixin

项目结构

创建后的项目结构：

my-first-uniappx/
├── src/
│   ├── pages/
│   │   ├── index/
│   │   │   └── index.vue
│   │   └── ...
│   ├── components/
│   ├── static/
│   ├── App.vue
│   └── main.ts          # TypeScript 入口
├── manifest.json
├── pages.json
├── vite.config.ts
├── tsconfig.json
└── package.json

运行项目

H5 平台

npm run dev:h5

浏览器会自动打开 http://localhost:3000

微信小程序

npm run dev:mp-weixin

项目会编译到 dist/dev/mp-weixin，使用微信开发者工具打开该目录。

创建第一个页面（TypeScript + Composition API）

1. 在 `src/pages` 目录下创建页面：

src/pages/
└── hello/
    └── hello.vue

2. 创建页面文件 `hello.vue`：

<template>
  <view class="container">
    <text class="title">{{ title }}</text>
    <button @click="handleClick">点击我</button>
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { onLoad } from '@dcloudio/uni-app'

const title = ref<string>('Hello uni-app-x!')

const handleClick = () => {
  uni.showToast({
    title: '按钮被点击了',
    icon: 'success'
  })
}

onLoad((options) => {
  console.log('页面加载', options)
})
</script>

<style scoped>
.container {
  padding: 20px;
  text-align: center;
}
.title {
  font-size: 24px;
  color: #333;
  margin-bottom: 20px;
}
</style>

3. 在 `pages.json` 中注册页面：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    },
    {
      "path": "pages/hello/hello",
      "style": {
        "navigationBarTitleText": "Hello"
      }
    }
  ]
}

创建第一个组件（TypeScript）

1. 在 `src/components` 目录下创建组件：

src/components/
└── my-button/
    └── my-button.vue

2. 组件代码：

<template>
  <button class="my-button" @click="handleClick">
    {{ text }}
  </button>
</template>

<script setup lang="ts">
interface Props {
  text?: string
}

const props = withDefaults(defineProps<Props>(), {
  text: '按钮'
})

const emit = defineEmits<{
  (e: 'click'): void
}>()

const handleClick = () => {
  emit('click')
}
</script>

<style scoped>
.my-button {
  background-color: #007aff;
  color: white;
  border: none;
  padding: 10px 20px;
  border-radius: 4px;
}
</style>

3. 在页面中使用：

<template>
  <view>
    <my-button text="点击我" @click="handleButtonClick"></my-button>
  </view>
</template>

<script setup lang="ts">
import MyButton from '@/components/my-button/my-button.vue'

const handleButtonClick = () => {
  console.log('按钮被点击')
}
</script>

与 uni-app 的区别

1. 技术栈

• uni-app：Vue 2/3 + JavaScript
• uni-app-x：Vue 3 + TypeScript + Vite

2. 开发体验

• 更好的 TypeScript 支持
• 更快的构建速度（Vite）
• 更好的代码提示

3. 性能

• 更小的包体积
• 更快的启动速度
• 更好的运行时性能

下一步

• 学习 uni-app-x 组件：参考 uniappx-project
• 学习 uni-app-x API：参考 uniappx-project
• 配置项目：参考 templates/project-templates.md

uni-app-x CLI 命令模板

官方文档

参考官方文档：https://uniapp.dcloud.net.cn/quickstart-cli.html

项目创建命令

使用官方模板

# 创建项目
npx degit dcloudio/uni-preset-vue-x my-project

# 或使用官方脚手架
npm create uni-app-x@latest my-project

使用 HBuilderX

1. 文件 → 新建 → 项目 2. 选择 uni-app x 3. 选择模板 4. 填写项目信息 5. 点击创建

项目运行命令

开发环境

# H5 平台
npm run dev:h5

# 微信小程序
npm run dev:mp-weixin

# App（需要 HBuilderX）
npm run dev:app

生产环境

# H5 平台
npm run build:h5

# 微信小程序
npm run build:mp-weixin

# App（需要 HBuilderX）
npm run build:app

常用命令

安装依赖

npm install

类型检查

# TypeScript 类型检查
npm run type-check

# 或使用 tsc
npx tsc --noEmit

代码检查

# ESLint 检查
npm run lint

# 自动修复
npm run lint:fix

一键创建项目脚本

#!/bin/bash
# create-uniappx-project.sh

PROJECT_NAME=$1

if [ -z "$PROJECT_NAME" ]; then
  echo "Usage: ./create-uniappx-project.sh <project-name>"
  exit 1
fi

echo "Creating uni-app-x project: $PROJECT_NAME"
npx degit dcloudio/uni-preset-vue-x $PROJECT_NAME
cd $PROJECT_NAME
npm install
echo "Project created successfully!"
echo "Run 'npm run dev:h5' to start development server"

项目初始化完整流程

# 1. 创建项目
npx degit dcloudio/uni-preset-vue-x my-project

# 2. 进入项目目录
cd my-project

# 3. 安装依赖
npm install

# 4. 初始化 Git（可选）
git init
git add .
git commit -m "Initial commit"

# 5. 运行项目
npm run dev:h5

参考资源

• uni-app-x 文档：https://doc.dcloud.net.cn/uni-app-x/
• TypeScript 文档：https://www.typescriptlang.org/
• Vite 文档：https://cn.vitejs.dev/

uni-app-x 项目模板

官方文档

参考官方文档：https://uniapp.dcloud.net.cn/quickstart-cli.html

标准项目结构

my-uniappx-project/
├── src/
│   ├── pages/                  # 页面目录
│   │   ├── index/
│   │   │   └── index.vue
│   │   └── ...
│   ├── components/             # 组件目录
│   │   └── ...
│   ├── static/                 # 静态资源
│   ├── utils/                  # 工具函数
│   ├── api/                    # API 接口
│   ├── store/                  # 状态管理（Pinia）
│   ├── App.vue                 # 应用入口
│   └── main.ts                 # TypeScript 入口
├── manifest.json               # 应用配置
├── pages.json                  # 页面路由配置
├── vite.config.ts              # Vite 配置
├── tsconfig.json               # TypeScript 配置
└── package.json

manifest.json 模板

{
  "name": "my-uniappx",
  "appid": "",
  "description": "uni-app-x 项目",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false,
  "uni-app-x": {
    "compilerVersion": "1.0.0",
    "vueVersion": "3",
    "typescript": true
  },
  "app-plus": {
    "usingComponents": true,
    "compilerVersion": 3
  },
  "h5": {
    "router": {
      "mode": "hash",
      "base": "/"
    }
  },
  "mp-weixin": {
    "appid": "",
    "setting": {
      "urlCheck": false
    },
    "usingComponents": true
  }
}

pages.json 模板

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "uni-app-x",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  }
}

页面模板（TypeScript + Composition API）

<template>
  <view class="container">
    <text class="title">{{ title }}</text>
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { onLoad, onShow, onReady, onHide, onUnload } from '@dcloudio/uni-app'

const title = ref<string>('Hello uni-app-x')

onLoad((options) => {
  console.log('页面加载', options)
})

onShow(() => {
  console.log('页面显示')
})

onReady(() => {
  console.log('页面初次渲染完成')
})

onHide(() => {
  console.log('页面隐藏')
})

onUnload(() => {
  console.log('页面卸载')
})
</script>

<style scoped>
.container {
  padding: 20px;
}
.title {
  font-size: 18px;
  color: #333;
}
</style>

组件模板（TypeScript）

<template>
  <view class="my-component">
    <text>{{ message }}</text>
  </view>
</template>

<script setup lang="ts">
interface Props {
  message?: string
}

const props = withDefaults(defineProps<Props>(), {
  message: 'Hello'
})

const emit = defineEmits<{
  (e: 'update', value: string): void
  (e: 'delete'): void
}>()
</script>

<style scoped>
.my-component {
  padding: 10px;
}
</style>

App.vue 模板

<template>
  <view id="app">
    <!-- 应用内容 -->
  </view>
</template>

<script setup lang="ts">
import { onLaunch, onShow, onHide } from '@dcloudio/uni-app'

onLaunch(() => {
  console.log('App Launch')
})

onShow(() => {
  console.log('App Show')
})

onHide(() => {
  console.log('App Hide')
})
</script>

<style>
/* 全局样式 */
</style>

main.ts 模板

import { createSSRApp } from 'vue'
import App from './App.vue'

export function createApp() {
  const app = createSSRApp(App)
  return {
    app
  }
}

vite.config.ts 模板

import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'

export default defineConfig({
  plugins: [uni()],
  server: {
    port: 3000,
    open: true
  }
})

tsconfig.json 模板

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "jsx": "preserve",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "types": ["@dcloudio/types"]
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"],
  "exclude": ["node_modules"]
}