創建并運行第一個 uni-app 項目

1. 前言

在前面的小節中，我們已經對 uni-app 做了簡單的介紹，相信大家都對 uni-app 有了一定的了解。

本小節帶領大家創建第一個 uni-app 項目。

創建 uni-app 項目有兩種方式：第一種是通過官方的開發者工具 HBuilder 來創建，第二種是通過 vue-cli 命令行創建。

2. 使用 HBuilderX 與使用 cli 創建項目的主要區別

使用 cli 創建項目，編譯器是安裝在單獨的項目下面的，升級時需要手動命令升級，只對這一個項目生效。

使用 HBuilderX 創建項目，編譯器是裝在 HBuilderX 的插件目錄下面了，HBuilderX 版本更新，編譯器就會一起更新升級，對所有項目生效。日常開發建議大家直接使用 HBuilder 創建項目就可以了。

3. HBuilder創建項目

HBuilderX 是 uni-app 官方推出的開發者工具，里面內置了開發環境，不需要額外配置 nodejs 環境，可以幫我們省去很多麻煩。

3.1 下載工具

先來點開官方網址下載 HBuilderX 開發者工具，建議下載App開發版。

HBuilderX：官方IDE下載地址

3.2 創建 uni-app 項目

接下來，我們通過剛剛下載的 HBuilderX 開發者工具創建一個 uni-app 項目，要跟著一起操作哦。點擊工具欄中的文件->新建->項目：

會出現一個彈窗，接下來我們需要選擇 uni-app 類型，輸入項目名稱，修改項目路徑，選擇合適的模板，點擊創建，項目就創建成功啦。

選擇模板的時候，有幾個模板選項。分別是：

• 默認模板：不會內置常用組件，想要自己安裝組件可以使用該模板。
• uni-ui 項目：內置很多常用的組件，日常開發推薦使用該模板。
• Hello uni-app：安裝了官方的組件和 API 示例，初次體驗的話可以使用該模板。

3.3 在項目中添加 HelloWorld

打開 pages/index/index.vue 文件，將 <template> 標簽的內容替換成下面的代碼。
實例：

<template>
    <view class="container">
        HelloWorld
    </view>
</template>

3.4 運行項目

我們來將上面添加的 HelloWorld 運行起來吧。

1. 運行到瀏覽器

點擊工具欄中的運行->運行到瀏覽器->選擇相應的瀏覽器運行：

選擇瀏覽器之后，HBuilderX 開發者工具會出現正在編譯的提示，第一次運行會慢一點，編譯成功后，自動打開瀏覽器并顯示項目的頁面?？梢钥吹?HelloWorld 打印出來了。

2. 運行到內置瀏覽器

點擊工具欄中的運行->運行到內置瀏覽器，會出現一個 Web 瀏覽器的彈出框，第一次打開會比較慢，需要耐心等一會才會出現項目的頁面。

3. 運行到手機或模擬器

使用這個功能需要先用數據線連接手機，否則會提示“未檢測到手機或模擬器，請稍后再試”。

數據線連接手機后，我們再點擊工具欄中的運行->運行到手機或模擬器。系統會自動在我們手機上面安裝 HBuilderX 手機版。

在手機上面打開 HBuilderX 手機版，就可以看到 HelloWorld 頁面。

Tips：
如果打開手機版 HBuilderX 沒有看到正確的頁面，可以關掉手機應用進程，重新打開看一下。
如果編譯出錯，點擊查看工具欄中的運行->運行到手機或模擬器->真機運行常見故障排除指南，排除錯誤。

4. 運行到小程序模擬器

第一次使用小程序模擬器，需要先安裝小程序開發者工具，并在工具欄->運行->運行到小程序模擬器->運行設置中設置小程序開發者工具安裝的路徑。

• 在微信開發者工具里運行

點擊工具欄中的運行->運行到小程序模擬器->微信開發者工具，即可在微信開發者工具里面體驗 uni-app。

在 HBuilderX 里面開發，微信開發者工具里面就可以看到實時效果。uni-app 會將項目編譯到根目錄的 unpackage/dist 目錄下面。

Tips：如果沒有成功運行可以做下面的操作。
如果微信開發者工具已經打開，關閉微信開發者工具，重試一下；
如果還是不行的話，建議將微信開發者工具升級到最新版本；
最后如果自動啟動微信開發工具失敗，可以手動在開發者工具中打開HBuilderX控制臺中提示的項目路徑。

• 在百度開發者工具里運行

點擊工具欄的運行->運行到小程序模擬器->百度開發者工具，在百度開發者工具中打開 HBuilderX 控制臺中提示的項目路徑，就可以在百度開發者工具中體驗 uni-app。

• 在支付寶小程序開發者工具里運行

點擊工具欄的運行->運行到小程序模擬器->支付寶小程序開發者工具，在支付寶小程序開發者工具中打開 HBuilderX 控制臺中提示的項目路徑，就可以在支付寶小程序開發者工具中體驗 uni-app。

• 在字節跳動開發者工具里運行

點擊工具欄的運行->運行到小程序模擬器->字節跳動開發者工具，在字節跳動開發者工具中打開 HBuilderX 控制臺中提示的項目路徑，就可以在字節跳動開發者工具中體驗 uni-app。

4. vue-cli 命令行創建項目

我們在終端通過 vue-cli 命令行創建 uni-app 項目，在創建項目之前，需要保證電腦已經配置了 nodejs 環境。

4.1 安裝 vue-cli

npm install -g @vue/cli

4.2 創建 uni-app 項目

創建正式版項目，對應 HBuilderX 最新正式版，最常用

vue create -p dcloudio/uni-preset-vue my-project

使用 alpha 版項目，對應 HBuilderX 最新 alpha 版，可能不太穩定

vue create -p dcloudio/uni-preset-vue#alpha my-alpha-project

創建項目的過程中會提示選擇項目模板，一般選擇默認模板就可以了。

如果想要選擇自定義模板，需要先填寫一個 uni-app 模板地址，這個地址可以是托管在 GitHub 上面的倉庫地址，地址格式為 userName/repositoryName，比如 dcloudio/uni-template-picture 就是下載圖片模板。

更多的下載方式，可以參考這個插件的說明：download-git-repo

4.3 運行uni-app

npm run dev:%PLATFORM%

%PLATFORM% 可取值如下：

Tips：
dev 模式編譯出的各平臺代碼存放于根目錄下的 /dist/dev/ 目錄，打開各平臺開發工具選擇對應的平臺目錄即可進行預覽（h5 平臺不會在此目錄，存在于緩存中）；
build 模式編譯出的各平臺代碼存放于根目錄下的 /dist/build/ 目錄，發布時選擇此目錄進行發布；
dev 和 build 模式的區別：dev 模式有 SourceMap 可以方便的進行斷點調試；build 模式進行代碼進行壓縮，體積更小更適合發布為正式版應用；進行環境判斷時，dev 模式 process.env.NODE_ENV 的轉換開發，構建模式 process.env.NODE_ENV 的轉換生產。

5. 小結

本節主要介紹了 uni-app 項目創建的兩種方式，本節的重點如下：

• 使用 HBuilderX 與使用 cli 創建項目的主要區別；
• 使用 HBuilderX 創建項目；
• 使用 vue-cli 命令行創建項目。