命令行创建uni-app项目的完整指南

1. 为什么选择命令行创建uni-app项目

在uni-app开发中，我们通常有两种创建项目的方式：通过HBuilderX可视化界面创建，或者通过命令行工具创建。对于有一定开发经验的程序员来说，命令行方式往往更受青睐。我在多个uni-app项目实践中发现，命令行创建方式具有几个显著优势：

首先，命令行方式更加灵活可控。我们可以精确指定项目模板、配置参数，并且能够轻松集成到自动化构建流程中。其次，这种方式对团队协作更友好，所有配置都以代码形式存在，避免了因IDE设置不同导致的环境差异问题。最重要的是，命令行创建的项目结构更加清晰，便于后续的定制化开发和维护。

2. 环境准备与工具安装

2.1 Node.js环境配置

命令行创建uni-app项目首先需要确保Node.js环境已经正确安装。建议使用LTS版本（目前推荐16.x或18.x），可以通过以下命令检查安装情况：

bash复制node -v
npm -v

如果尚未安装，可以从Node.js官网下载对应操作系统的安装包。安装完成后，建议配置npm的国内镜像源以加速后续的包下载：

bash复制npm config set registry https://registry.npmmirror.com

2.2 Vue CLI安装与配置

uni-app官方推荐使用@vue/cli作为脚手架工具。全局安装最新版本的Vue CLI：

bash复制npm install -g @vue/cli

安装完成后，可以通过以下命令验证安装是否成功：

bash复制vue --version

注意：如果系统中已经安装了旧版本的Vue CLI，建议先卸载旧版本再安装新版本，以避免潜在的兼容性问题。

3. 创建uni-app项目

3.1 初始化项目

在准备好基础环境后，我们可以开始创建uni-app项目。首先选择一个合适的目录，然后执行以下命令：

bash复制vue create -p dcloudio/uni-preset-vue my-uni-app

这个命令会使用uni-app官方提供的预设模板来初始化项目。执行后会进入交互式配置界面，我们需要做出一些关键选择。

3.2 模板选择与配置

在交互式界面中，我们会看到几个重要选项：

1. 模板选择：推荐选择"默认模板"或"自定义模板"。对于初学者，"默认模板"已经包含了uni-app开发所需的基本配置。

2. CSS预处理器：根据团队习惯选择Less或Sass。我个人更推荐Sass，因为它的社区生态更活跃。

3. ESLint配置：建议开启并选择"标准配置"，这有助于保持代码风格一致。

4. 单元测试：对于中小型项目可以暂时不选，大型项目可以考虑添加。

配置完成后，脚手架会自动下载模板并安装依赖。这个过程可能会花费几分钟时间，取决于网络速度。

4. 项目结构与关键文件解析

4.1 基础目录结构

成功创建项目后，我们会看到以下核心目录结构：

code复制my-uni-app/
├── public/                # 静态资源
├── src/                   # 主要开发目录
│   ├── pages/             # 页面目录
│   ├── static/            # 静态资源
│   ├── App.vue            # 应用入口组件
│   └── main.js            # 应用入口JS
├── package.json           # 项目配置
└── vue.config.js          # Vue CLI配置

4.2 关键配置文件说明

1. package.json：定义了项目依赖和脚本命令。特别需要注意的是dev:%PLATFORM%和build:%PLATFORM%系列命令，它们用于启动不同平台的开发或构建。

2. vue.config.js：这是Vue CLI的核心配置文件。uni-app已经为我们预设了必要的配置，包括多平台支持、路径别名等。我们可以在需要时修改这个文件来定制构建行为。

3. manifest.json：位于src目录下，这个文件定义了应用的全局配置，包括应用名称、图标、启动页面等。这个文件在项目创建后需要手动配置。

5. 开发与调试

5.1 启动开发服务器

要启动开发环境，我们可以运行以下命令：

bash复制npm run dev:%PLATFORM%

其中%PLATFORM%可以是h5（网页）、mp-weixin（微信小程序）、mp-alipay（支付宝小程序）等。例如，要开发微信小程序：

bash复制npm run dev:mp-weixin

启动后，项目会自动编译并在控制台输出访问地址。对于小程序平台，编译结果会生成在dist目录下，可以用对应平台的开发者工具导入查看。

5.2 常用开发命令

除了开发命令外，还有一些其他常用命令：

• npm run build:%PLATFORM%：构建生产环境版本
• npm run lint：运行代码检查
• npm run serve：启动H5开发服务器（仅H5平台）

6. 项目定制与优化

6.1 添加新页面

在uni-app中添加新页面非常简单：

1. 在src/pages目录下创建新的文件夹，例如user
2. 在文件夹中创建user.vue文件作为页面组件
3. 在pages.json中注册新页面：

json复制{
  "pages": [
    ...其他页面,
    {
      "path": "pages/user/user",
      "style": {
        "navigationBarTitleText": "用户中心"
      }
    }
  ]
}

6.2 配置跨平台适配

uni-app的一个强大特性是它的跨平台能力。我们可以通过条件编译来实现平台特定的代码：

javascript复制// #ifdef H5
console.log('这段代码只在H5平台执行');
// #endif

// #ifdef MP-WEIXIN
console.log('这段代码只在微信小程序平台执行');
// #endif

7. 常见问题与解决方案

7.1 依赖安装失败

如果在项目创建或依赖安装过程中遇到问题，可以尝试以下步骤：

1. 清除npm缓存：npm cache clean --force
2. 删除node_modules目录和package-lock.json
3. 重新运行npm install

7.2 小程序真机调试问题

在进行小程序真机调试时，可能会遇到以下问题：

1. 图片不显示：检查图片路径是否正确，小程序中需要使用相对路径或网络路径
2. 样式差异：不同平台对CSS的支持程度不同，可以使用条件编译处理平台差异
3. API不可用：某些API只在特定平台可用，使用前应该检查API兼容性

7.3 性能优化建议

随着项目规模增长，可以考虑以下优化措施：

1. 按需引入组件：避免一次性加载所有组件
2. 分包加载：将不常用的功能放到分包中
3. 图片压缩：使用工具压缩静态图片资源
4. 减少setData调用：在小程序中，频繁调用setData会影响性能

8. 进阶开发技巧

8.1 自定义组件开发

uni-app支持Vue的单文件组件开发方式。创建自定义组件时，建议：

1. 在src/components目录下组织组件
2. 使用有意义的组件名前缀，如my-button、user-avatar等
3. 通过props定义明确的组件接口
4. 为组件添加必要的插槽(slot)支持

8.2 状态管理

对于复杂应用，建议使用Vuex进行状态管理。uni-app内置了Vuex支持，可以通过以下步骤添加：

1. 安装Vuex：npm install vuex --save
2. 创建src/store目录并添加store模块
3. 在main.js中引入并挂载store

8.3 混合开发模式

uni-app支持原生插件和混合开发。如果需要使用原生功能：

1. 创建原生插件或使用现有插件
2. 在manifest.json中配置插件
3. 通过uni.requireNativePlugin调用原生功能

9. 项目构建与发布

9.1 构建生产版本

准备发布应用时，需要构建生产环境版本：

bash复制npm run build:%PLATFORM%

构建完成后，产物会生成在dist目录下。不同平台的发布流程略有不同：

• H5：部署到Web服务器
• 微信小程序：使用微信开发者工具上传
• App：通过HBuilderX进行云端打包

9.2 持续集成

对于团队项目，建议配置CI/CD流程。基本步骤包括：

1. 在代码仓库中配置CI脚本
2. 设置自动构建和测试
3. 配置自动部署流程

可以使用GitHub Actions、Jenkins等工具实现自动化流程。

10. 项目维护与升级

10.1 依赖管理

定期更新项目依赖很重要，但需要注意：

1. 使用npm outdated检查过期的依赖
2. 一次只更新一个主要依赖，避免同时引入多个破坏性变更
3. 更新后充分测试所有功能

10.2 uni-app版本升级

升级uni-app版本时，建议：

1. 查阅官方升级指南和变更日志
2. 先在测试环境验证升级
3. 特别注意破坏性变更的影响
4. 逐步升级，不要跳过多个主要版本

在实际项目中，我通常会创建一个升级检查清单，列出所有需要验证的关键功能点，确保升级不会影响现有功能。