：移動端Git配置與環(huán)境對齊指南)
1. 初識DevCloud與CodeHub為什么移動端團隊要重構代碼托管鏈路我們團隊之前一直用自建Git服務器托管代碼服務器放在某辦公樓的機房里平時用著還行一旦遇到網絡抖動或者機房斷電整個團隊的提交和拉取就全卡住了。最難受的是iOS和Android兩個端的同學要用不同的工具鏈代碼托管和構建環(huán)境割裂得很厲害每次發(fā)版都要人工協(xié)調半天。后來我們立項做一款新的移動端管理App決定把代碼托管和云端構建整體遷到華為云DevCloud上核心的代碼倉庫放到CodeHub。這件事看起來只是把Git倉庫換個地方放實際操作下來牽扯到的東西比我預想的多得多SSH密鑰怎么配、iOS和Android兩端如何共用一套托管策略、本地環(huán)境怎么和云端構建機對齊、CI/CD流水線怎么串聯(lián)起來。這篇就是整個系列的第一篇專門講Git連接CodeHub以及iOS、Android的本地和云端開發(fā)環(huán)境怎么一步步搭起來。如果你正準備把移動端項目遷到華為云或者剛開始用DevCloud和CodeHub這篇應該能幫你省不少時間。我個人的體會是遷移最怕的不是技術難度而是兩邊環(huán)境不一致。本地是本地云端是云端代碼托管又是中間那一環(huán)任何一環(huán)版本對不上后面跑流水線的時候就會冒出一堆莫名其妙的報錯。所以這篇文章會從代碼托管這條鏈路切入先把Git和CodeHub的連接徹底講透再分別展開iOS和Android這邊的環(huán)境配置最后把云端構建的環(huán)境對齊和常見坑也一并說清楚。1.1 華為云DevCloud到底是什么和CodeHub是什么關系先把這個概念理清楚。華為云DevCloud現(xiàn)在控制臺里也經常看到CodeArts品牌指的是同一套DevOps服務是一個一站式研發(fā)云平臺涵蓋項目管理、代碼托管、編譯構建、部署發(fā)布、流水線等能力。而CodeHub是其中負責代碼托管的模塊本質上就是一個基于Git的云端倉庫服務和GitHub、GitLab屬于同類產品只是它深度集成在華為云的整體生態(tài)里。對于移動端團隊來說CodeHub解決的核心痛點是倉庫不再依賴內網服務器團隊成員在任意網絡環(huán)境都能拉取和推送代碼倉庫權限可以和DevCloud的項目成員體系打通同時代碼倉庫和構建服務天然聯(lián)動后續(xù)做CI/CD的時候不需要額外寫一堆腳本去對接。這里有一個很重要的認知CodeHub不是簡單的云盤版Git倉庫它和DevCloud的流水線、編譯構建任務是聯(lián)動的。你在本地提交代碼到CodeHubCodeHub觸發(fā)Webhook云端構建機拉取最新代碼開始編譯整個鏈條是通的。如果只是把代碼推到遠程倉庫而不用云端構建那這套遷移的意義就打了一半折扣。1.2 為什么我覺得這一步值得單獨寫一篇很多教程上來就直接讓你執(zhí)行git clone忽略了環(huán)境搭建的系統(tǒng)性。但移動端開發(fā)和后端不一樣涉及的本地工具鏈很重iOS必須用macOS加XcodeAndroid需要JDK、Android Studio、SDK、Gradle一大堆。如果只講倉庫配置不講環(huán)境對齊你本地跑得好好的代碼到了云端構建機上大概率編譯不過。另外一個容易被忽略的問題是iOS和Android兩個平臺對Git的使用習慣有差異。iOS端通常直接在Xcode里操作GitAndroid端則習慣用Android Studio的VCS菜單或者命令行。兩端提交代碼時對.gitignore的處理、對二進制文件的管理方式也不同。既然放在同一個CodeHub倉庫下這些差異就必須在環(huán)境搭建階段就統(tǒng)一規(guī)范好。所以我這篇的定位是先搞定代碼托管這一層再搞定兩端環(huán)境這一層兩者的交叉點就是本地Git配置和SSH密鑰。下面我從最基礎的SSH配置開始講這是連接CodeHub的第一道關卡。2. Git與CodeHub建立連接SSH密鑰生成、配置與驗證全程記錄2.1 本地Git環(huán)境準備與版本選擇無論iOS還是Android端第一步都是在本地裝好Git。macOS上我推薦用Homebrew安裝命令是brew install git安裝完檢查版本git --version這里有一個需要注意的細節(jié)macOS自帶的Git版本可能比較老而且Xcode如果更新過系統(tǒng)的Git路徑可能會被Xcode的命令行工具覆蓋導致版本混亂。建議用Homebrew的Git并確保which git指向/usr/local/bin/git或/opt/homebrew/bin/git不要指向/usr/bin/git。Windows端推薦直接裝Git for Windows安裝時選Use Git from the Windows Command Prompt和Checkout as-is, commit as-is這兩個選項前者方便在CMD和PowerShell里直接用git命令后者避免行尾符轉換引發(fā)一堆莫名奇妙的diff。Android端的同學還要裝JDK和Android Studio這個我在第四部分細說這里先保證Git本身是可用的。2.2 SSH密鑰對生成一對密鑰還是兩對密鑰連接CodeHub有兩種方式HTTPS和SSH。HTTPS每次push都要輸入用戶名密碼可以配置credential緩存但團隊協(xié)作時容易出問題SSH則是通過公鑰認證配置好之后push/pull都不需要再輸密碼。移動端團隊我強烈建議用SSH。生成SSH密鑰的命令ssh-keygen -t rsa -b 4096 -C your_emailexample.com -f ~/.ssh/id_rsa_devcloud這里有幾個參數(shù)說明一下-t rsa指定算法雖然現(xiàn)在也支持Ed25519但CodeHub對RSA的兼容性最穩(wěn)妥4096位長度足夠安全-C是注釋建議填你在DevCloud注冊的郵箱方便后期識別-f指定文件名我習慣不以默認的id_rsa命名而是單獨命名為id_rsa_devcloud這樣如果電腦上還有其他Git平臺比如自建GitLab或GitHub的密鑰就不會互相覆蓋生成之后~/.ssh目錄下會出現(xiàn)兩個文件id_rsa_devcloud私鑰和id_rsa_devcloud.pub公鑰。私鑰留在本地公鑰要填到CodeHub后臺。如果你同時維護多個代碼托管平臺我建議在~/.ssh/config里做區(qū)分。示例配置Host codehub HostName codehub.devcloud.huaweicloud.com User git IdentityFile ~/.ssh/id_rsa_devcloud這樣后面git clone時可以直接用gitcodehub:Group/Repo.git這種寫法Git會自動使用對應密鑰。沒有這個配置也不影響功能但配置了之后在多密鑰環(huán)境下會省掉很多麻煩。2.3 公鑰配置到CodeHub后臺與本地驗證登錄華為云DevCloud控制臺進入CodeHub服務在個人設置里找到SSH密鑰管理把id_rsa_devcloud.pub里的內容完整復制粘貼進去保存即可。這個公鑰和你的華為云賬號綁定同一賬號下的所有CodeHub倉庫都能用。然后在本地驗證連通性ssh -T gitcodehub.devcloud.huaweicloud.com第一次連接會提示確認指紋輸入yes回車。如果返回類似于Welcome to CodeHub的歡迎信息說明密鑰配置成功。如果提示權限拒絕Permission denied按順序排查公鑰是否完整復制有沒有多復制空格或者漏掉末尾的郵箱注釋私鑰文件的權限是否過寬運行chmod 600 ~/.ssh/id_rsa_devcloudssh-add -l查看私鑰是否已加載到ssh-agent沒有就執(zhí)行ssh-add ~/.ssh/id_rsa_devcloud這里我要特別提一個坑Windows環(huán)境下如果你用的是Git for Windows自帶的OpenSSH但同時又裝了別的SSH工具可能會遇到公鑰能配但就是連不上的問題大概率是SSH客戶端選擇沖突。解決辦法是在Git for Windows的安裝選項里明確設置Use OpenSSH或者在系統(tǒng)環(huán)境變量里把GIT_SSH指向正確的ssh.exe路徑。2.4 創(chuàng)建CodeHub倉庫并完成首次push在CodeHub后臺新建倉庫填充倉庫名選擇可見范圍私有還是公開。國內團隊項目的代碼倉庫保險起見都選私有同時注意DevCloud里項目的成員權限配置——不是項目成員的人看不到倉庫這一點和GitLab的Group權限模型類似。倉庫創(chuàng)建后CodeHub會給出完整的命令行指引HTTPS和SSH兩種方式都有。我們按SSH的方式操作。以iOS端為例如果項目已經存在本地cd your-ios-project git init git add . git commit -m Initial commit git remote add origin gitcodehub.devcloud.huaweicloud.com:GroupName/RepoName.git git push -u origin masterAndroid端的操作完全一致。這里提醒幾個細節(jié)首次git add .之前務必先把.gitignore寫好。iOS項目至少要忽略Pods/、DerivedData/、*.xcuserstateAndroid項目至少要忽略build/、local.properties、.idea/。這些目錄一旦被提交進去后面再想清理就得用git rm -r --cached麻煩不說還容易誤刪分支命名建議統(tǒng)一用master或mainDevCloud的倉庫默認分支可以在后臺改。后續(xù)如果走Git Flow再按需建develop、release分支首次push的倉庫建議不要太大超過幾百MB時用git gc壓縮一下對象否則網絡不穩(wěn)定時容易push失敗3. iOS本地與云端開發(fā)環(huán)境Xcode、模擬器與構建機的配合3.1 Xcode版本選擇與命令行工具iOS開發(fā)繞不開Xcode。官方渠道是App Store安裝等Xcode下載完再裝Command Line Toolsxcode-select --install裝完后把命令行工具路徑指向Xcode自帶的工具鏈sudo xcode-select -s /Applications/Xcode.app/Contents/Developer然后驗證xcode-select -p這一步看似簡單但我遇到過一個很頭疼的問題Xcode更新到新版本后xcodebuild命令報錯找不到SDK。這個問題的根源是xcode-select的路徑被重置了或者多個Xcode版本并存導致系統(tǒng)指向了錯誤的Developer目錄。所以每次升級Xcode后我都習慣先跑一遍xcode-select -p確認路徑再跑xcodebuild -version確認版本。云端構建這部分華為云DevCloud提供macOS構建機。這里的關鍵點是本地Xcode主版本和云端構建機的Xcode版本必須一致或至少兼容。比如本地用Xcode 15云端也盡量保持在15這個大版本。如果不一致最容易出現(xiàn)的情況是本地編譯鏈接通過提交上去之后云端構建報錯什么SDK版本過低parameter of xxx is unavailable之類看起來像是代碼問題實際是工具鏈版本不一致導致的。DevCloud的構建任務配置頁面里可以選擇構建機類型和Xcode版本這一步一定要和本地對齊。我記過一次很典型的例子A同學本地Xcode 16提交的代碼云端的構建機還停留在Xcode 14結果一跑流水線就報iOS 17 SDK required。當時排查了半小時最后發(fā)現(xiàn)不是代碼問題純粹是版本錯位。3.2 本地模擬器與真機調試的環(huán)境細節(jié)模擬器本身不算復雜但涉及證書簽名的環(huán)節(jié)容易卡人。模擬器構建不需要證書直接CommandR就能跑真機調試需要Apple Development證書和描述文件。這個證書體系對新手來說是第一道坎。實操層面在Xcode的Signing Capabilities面板里勾選Automatically manage signingXcode會自動幫你生成開發(fā)證書和描述文件。但如果你是用CodeHub拉下來的倉庫且項目里的Bundle Identifier和當前開發(fā)者賬號不匹配會自動簽名會失敗。我一般建議確認團隊里每個開發(fā)者在DevCloud項目的成員列表里并且有對應的Apple開發(fā)者賬號權限項目里如果涉及推送、App Group等能力在Apple開發(fā)者后臺提前配好不要提交個人證書和描述文件到Git倉庫用Xcode的自動管理機制代替云端iOS構建時證書的處理方式不同需要把證書和描述文件上傳到DevCloud的證書管理里構建時通過配置關聯(lián)。這個我放到第五節(jié)講流水線時一起說。3.3 使用Xcode連接CodeHub倉庫的操作路徑Xcode內置了Git客戶端在項目初始化的界面上Xcode 15及以上的版本在創(chuàng)建項目時可以選擇源碼控制。如果是已有的項目要通過Xcode連接CodeHub可以在Xcode的Source Control菜單里添加遠程倉庫填入CodeHub的SSH地址。這里有個Xcode使用上的細節(jié)Xcode的Git界面在查看Diff、提交、推送時還算好用但遇到沖突解決時我還是建議切換到命令行或第三方工具。Xcode的沖突解決界面做得比較簡陋多個紛爭并發(fā)時容易點錯導致誤把別人的修改覆蓋掉。比較穩(wěn)妥的工作流是在Xcode里寫代碼、看Diff、做常規(guī)提交切換分支、合并、處理沖突時用命令行工具推送到遠程之前先在命令行看一遍git log和git status另外Xcode項目文件.xcodeproj是結構化目錄Git合并時經常出現(xiàn)項目文件沖突。團隊協(xié)作時最好約定一個規(guī)則同一時間段內盡量不要多人同時修改項目配置比如簽名配置、Target設置這些能避免大量無意義的沖突。4. Android本地與云端開發(fā)環(huán)境Android Studio、Gradle與CodeHub的三角組合4.1 JDK與Android Studio安裝的版本匹配問題Android端的本地環(huán)境搭建第一個坑就是JDK版本。Android Studio新版本如Koala及以后內置了JBRJetBrains Runtime但Gradle構建時仍需要Java環(huán)境。常見的匹配關系大致如下Gradle版本JDK版本要求AGP版本建議7.xJDK 11或177.x8.xJDK 178.x8.5JDK 17或218.5如果不匹配最常見的就是Unsupported class file major version這類報錯。根本原因是Gradle運行時的JDK和編譯字節(jié)碼的JDK不一致。Android Studio自帶JBR但命令行構建時比如在CI環(huán)境里系統(tǒng)默認的java可能是Oracle JDK或者OpenJDK的某個版本?，F(xiàn)在大部分企業(yè)項目的實踐經驗是在項目根目錄的gradle.properties或.java-version文件里固定JDK版本然后確保本地的JAVA_HOME指向正確的路徑。Android Studio安裝完成后還要通過SDK Manager下載對應版本的Android SDK Platform、Build Tools和NDK如果你的項目用C/C代碼。SDK的路徑配置很重要Android Studio默認會寫到用戶目錄下的Android/Sdk這個路徑務必記下來后面配置云端構建時還要用到。4.2 Gradle初始化與項目依賴同步Android項目的構建核心是Gradle。新建項目或從CodeHub拉取項目后Android Studio會自動同步Gradle依賴。但如果是從倉庫拉的老項目大概率會遇到兩個問題Gradle wrapper版本和本地已安裝的Gradle版本不匹配依賴源拉取超時第一個問題的解決辦法是修改gradle/wrapper/gradle-wrapper.properties里的distributionUrl或者直接在Android Studio里調整Gradle JDK版本。第二個問題在實際中更常見經常是國內網絡環(huán)境下默認的Google Maven倉庫拉取慢。常用的做法是在項目級build.gradle里配置阿里云鏡像倉庫buildscript { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/gradle-plugin } } }這個配置我一般建議只在本地開發(fā)環(huán)境加提交代碼時通過git update-index --skip-worktree build.gradle的方式避免誤提交或者干脆在CI環(huán)境里用環(huán)境變量控制鏡像源。原因也很簡單如果所有團隊成員都用自己的鏡像配置可能會出現(xiàn)依賴源不一致、構建結果不一致的情況。4.3 Android Studio的VCS配置與從CodeHub拉取項目Android Studio內置了Git支持首次打開項目后通過VCS菜單可以把本地倉庫切換到CodeHub遠程。操作路徑是VCS Git Remotes添加CodeHub的SSH地址。這里有一個重要的操作習慣Android Studio里右鍵項目文件時會看到很多Git相關的操作但不要用Android Studio的Git去處理項目文件的沖突。Android Studio在合并多個模塊的Gradle腳本時自動合并策略有時候會把兩個不相關的改動強行合并到一起產生邏輯層面的錯誤。一般認為最穩(wěn)妥的Android Git操作順序是在Android Studio里開發(fā)編碼切換到命令行執(zhí)行git pull --rebase拉取遠端最新代碼手動處理沖突后再回Android Studio刷新項目本地編譯通過后再push到CodeHub這樣看似多了一步實際能避免很多Git操作造成的問題。4.4 Android云端構建環(huán)境的認知本質上就是一臺預裝SDK的Linux機器DevCloud的Android構建機本質上是一臺預裝了JDK、Android SDK、Gradle的Linux虛擬機。你在本地能跑通的構建理論上云端也能跑通前提是環(huán)境對齊。這里最容易出問題的點有三個SDK版本本地裝的是API 34云端構建機可能只預裝了API 33編譯時就會報SDK component platforms;android-34 was not found。解決辦法是在流水線構建任務里加上SDK安裝步驟或者通過腳本自動下載對應版本Gradle緩存云端構建機每次構建時如果不是同一臺機器Gradle的依賴緩存可能為空構建耗時明顯拉長。DevCloud構建任務支持配置緩存策略建議開啟簽名配置release包的簽名文件.jks不要放進倉庫本地構建時用local.properties引用簽名路徑云端構建時通過DevCloud的私密參數(shù)下發(fā)我在初期的項目里吃過虧本地release構建一直正常云端一跑就報Key was created with errors排查后發(fā)現(xiàn)是簽名文件被加密后云端構建機上解密生成的臨時文件權限不對。這種問題很隱蔽寫在流水線配置里要注意文件的加密與解密順序。5. 云的流水線配置從代碼提交到自動化構建的核心鏈路5.1 在DevCloud里創(chuàng)建編譯構建任務DevCloud的CI/CD核心是流水線Pipeline構建任務可以單獨配置也可以放在流水線里串聯(lián)。以Android為例最基本的構建任務是從CodeHub拉取代碼執(zhí)行./gradlew assembleDebug產出APK。流程上先在DevCloud控制臺進入編譯構建新建構建任務選擇代碼源為CodeHub選中對應的倉庫和分支選擇構建模板Android有現(xiàn)成的模板會幫你填充Gradle命令和SDK路徑配置構建機類型一般選Linux Docker保存之后手動執(zhí)行一次看構建日志這里有一個很關鍵的點構建任務拉取代碼時用的憑證。DevCloud的構建任務默認使用你創(chuàng)建任務時關聯(lián)的賬號權限但它拉取代碼的憑證是獨立的。如果構建日志里出現(xiàn)Authentication failed不要慌去構建任務的代碼源配置里檢查是否選擇了正確的CodeHub倉庫訪問權限。另一種路徑是你在自己的流水線里寫自定義腳本用git clone命令手動拉取代碼然后執(zhí)行構建命令。這種方式的靈活度最高但你必須自己管理SSH密鑰或HTTPS憑證在構建機上的存放位置稍有不慎就會把密鑰泄露到構建日志里。我建議新手優(yōu)先用DevCloud自帶代碼源配置不要在腳本里手動處理認證。5.2 iOS云端構建的證書管理與描述文件策略iOS云端構建相對Android更繁瑣核心在于證書和描述文件不能像Android那樣簡單用密鑰參數(shù)。DevCloud提供證書管理功能把.p12證書文件和.mobileprovision上傳到云端構建時綁定到對應任務。實操中我發(fā)現(xiàn)以下幾個環(huán)節(jié)是坑點高發(fā)區(qū)證書導出在鑰匙串訪問里導出.p12時注意勾選包含私鑰并設置導出密碼。這個密碼在云端構建配置時要用到描述文件選擇確保描述文件包含的設備列表包含運行真機的設備或者使用App Store類型描述文件。如果描述文件不匹配簽名階段會直接報錯構建命令的選擇xcodebuild的-exportArchive階段要指定ExportOptions.plist這個文件里寫的teamID、method要和證書匹配。我們在實際項目中維護了一個ExportOptions.plist模板放在倉庫里避免每個人本地手寫導出配置構建日志里常見的errSecInternalComponent錯誤大多是證書導入到云端Keychain時權限問題。DevCloud的文檔里會提到構建機鑰匙串權限設置建議仔細閱讀這里不再展開。5.3 流水線串聯(lián)提交觸發(fā)、靜態(tài)檢查與產物歸檔當兩端構建任務都跑通后就可以把它們串到一條流水線里。DevCloud里創(chuàng)建流水線經過這幾個階段代碼提交時自動觸發(fā)在倉庫配置Webhook或者流水線的代碼源綁定CodeHub倉庫每次push自動啟動流水線并行執(zhí)行iOS構建和Android構建在邏輯上相互獨立可以配置成并行階段節(jié)省總耗時靜態(tài)檢查可選DevCloud集成了代碼檢查服務可以加在構建前攔截明顯的編碼規(guī)范問題產物歸檔把生成的.ipa和.apk文件歸檔到DevCloud的軟件發(fā)布庫或制品庫方便測試同學直接下載這里分享一下我對自動化程度的建議不是流水線越復雜越好。早期階段兩端各一條簡單的構建任務加上手動觸發(fā)已經比人工打包進步一大截。等團隊穩(wěn)定了再逐步加自動化觸發(fā)、代碼檢查、自動部署到測試環(huán)境。一上來就配置全自動鏈路維護成本會很高而且出現(xiàn)問題后排查難度大。5.4 云端構建機與本地環(huán)境的一致性維護清單這是一個我強烈建議做成文檔的清單。我們在實際運營中總結出來的一致性維護項包括檢查項本地云端構建機Xcode版本Xcode 15.xXcode 15.xAndroid SDK平臺API 34構建腳本中動態(tài)安裝JDK版本JDK 17JDK 17Gradle版本由wrapper指定使用wrapper簽名方式本地jks文件云端證書管理依賴源海外或鏡像源與本地保持一致這個清單不是一勞永逸的。每次系統(tǒng)升級、工具鏈更新都要重新對齊一輪。特別是Xcode大版本更新后SDK特性變化很大本地一升級云端立刻要跟進否則下一次云端構建就會失敗。6. 環(huán)境搭建避坑實錄版本、超時與權限邊界的經典坑6.1 Xcode升級后xcodebuild路徑錯亂的處理開頭提到過xcode-select的問題再展開講一次具體案例。有一次Xcode從15.2升到15.3之后團隊里幾個iOS開發(fā)同時報告在終端跑xcodebuild時提示找不到這個命令。排查后發(fā)現(xiàn)原因是升級過程中系統(tǒng)把/Library/Developer/CommandLineTools激活成了默認開發(fā)者目錄而xcodebuild實際上在Xcode.app內部。運行sudo xcode-select -s /Applications/Xcode.app/Contents/Developer即可解決。此外如果安裝了多個Xcode版本比如Xcode_14.x和Xcode_15.x并存建議在構建腳本里顯式指定DEVELOPER_DIR環(huán)境變量否則不同終端環(huán)境可能選到不同的Xcode構建結果都會不一樣。這里我給的方案是在項目根目錄維護一個env.sh腳本里面寫好export DEVELOPER_DIR/Applications/Xcode.app/Contents/Developer export JAVA_HOME/path/to/jdk-17每次打開新終端或者進入項目目錄時先source env.sh從源頭避免環(huán)境錯亂。6.2 Gradle依賴下載超時的排查鏈路Android構建最容易出現(xiàn)的經典坑就是依賴下載超時。表現(xiàn)是構建日志里出現(xiàn)類似Could not resolve com.android.tools.build:gradle:8.x.x或Connection timed out。這時候不要急著重試先按順序排查確認distributionUrl對應的Gradle版本能否從網絡正常下載檢查倉庫地址是否可訪問直接在瀏覽器里訪問一下對應URL檢查本機是否有代理或防火墻攔截了相關域名如果用的是鏡像源確認鏡像源同步完整在實際案例里我們遇到過鏡像源只同步了部分模塊導致解析失敗的情況這時候把缺失的倉庫臨時切回Google官方倉庫即可。另外合理配置Gradle離線緩存也能顯著緩解~/.gradle/caches目錄的緩存可以復制到云端構建機的持久化磁盤避免每次構建從零下載。6.3 敏感文件入庫的補救流程經常有同事在配置環(huán)境時臨時改了local.properties提交代碼時不小心把這個文件帶進倉庫。這個文件里通常含有SDK路徑、本地簽名文件路徑等信息不應該進倉庫。補救流程分兩步# 第一步把文件從Git追蹤中移除 git rm --cached local.properties # 第二步加入.gitignore避免再次誤提交 echo local.properties .gitignore git commit -m Remove local.properties from version control但如果這個文件已經被推送到了遠程倉庫光這么做還不夠因為歷史記錄里仍然存在該文件內容。為了徹底移除要用git filter-branch或git filter-repo重寫歷史。這個操作會導致倉庫的commit hash變化如果倉庫已經有多人協(xié)作重寫歷史前必須和團隊成員確認否則其他人的本地分支全部會失聯(lián)。我個人經驗是在項目初期就嚴格把關.gitignore比事后補救成本低得多。團隊里可以做一次代碼評審約定凡是涉及本地環(huán)境信息的文件一律不入庫。6.4 權限邊界與團隊成員協(xié)作的注意事項CodeHub的權限模型里代碼倉庫的訪問權限與DevCloud的項目成員角色綁定常見角色有項目經理、開發(fā)人員、測試人員、瀏覽者等。開發(fā)人員默認有倉庫的push權限測試人員只有只讀權限這一點在配置完權限后要告知每位成員避免出現(xiàn)測試同學想拉代碼卻拉不下來的疑問。還有一個容易忽略的點成員從DevCloud項目里移除后他/她原來的SSH公鑰會立即失效哪怕公鑰還留在CodeHub的個人設置里。這是一個安全設計但如果項目內人員流動頻繁新成員加入后一定要走加入項目的流程而不是單獨添加公鑰后者容易在忘卻后造成權限邊界混亂。7. 一個完整的實操演示從零連接CodeHub到兩端構建通過這部分我以團隊里真實走過的路徑為藍本整理出一份可以直接對照操作的完整流程清單。假設我們的項目叫某跨平臺管理AppiOS和Android兩個端的代碼放在同一個CodeHub倉庫里用不同目錄區(qū)分也可以是兩個獨立倉庫邏輯一致這里以單倉庫為例。7.1 初始化階段本地項目與CodeHub倉庫的關聯(lián)第一步在CodeHub創(chuàng)建一個空倉庫例如mobile-app。創(chuàng)建時選私有初始化時不要勾選生成README和.gitignore保持倉庫為空因為我們本地項目已存在。第二步在項目根目錄建立.gitignore。iOS和Android雙端目錄結構示例# iOS Pods/ DerivedData/ *.xcuserstate xcuserdata/ # Android build/ .gradle/ local.properties .idea/ *.apk *.aab captures/ # 通用 .DS_Store *.log第三步執(zhí)行本地Git初始化并連接遠程git init git add . git commit -m Initial commit git remote add origin gitcodehub.devcloud.huaweicloud.com:YourGroup/mobile-app.git git push -u origin master這個階段遇到最多的問題就是push時提示Permission to XXX denied按第2.3節(jié)的方法排查密鑰配置。等push成功CodeHub網頁端能看到代碼就說明Git連接這一環(huán)徹底打通了。7.2 iOS本地編譯驗證與云端任務創(chuàng)建本地打開Xcode確認能直接編譯運行項目。然后到DevCloud創(chuàng)建iOS構建任務主要內容包括代碼源選擇CodeHub倉庫分支選擇master構建機選擇macOS類型構建模板選擇Xcode相關模板在證書管理里導入.p12和.mobileprovision構建命令選擇xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Release clean archive并指定導出選項這一步容易出的問題構建機型號不同xcworkspace的Pod安裝情況也不同。如果項目使用CocoaPods要確保構建前先執(zhí)行pod install否則workspace無法生成構建直接失敗。7.3 Android本地編譯驗證與云端任務創(chuàng)建Android端同樣先確保本地能跑通./gradlew assembleDebug。然后到DevCloud創(chuàng)建Android構建任務代碼源選擇同一CodeHub倉庫構建機類型選擇Linux構建命令填寫./gradlew clean assembleDebug配置JDK和SDK路徑如果構建時下載依賴慢開啟Gradle緩存這里的關鍵是SDK路徑。DevCloud的Linux構建機預裝了SDK但版本可能不是你需要的。我們的做法是在構建腳本開頭動態(tài)安裝SDK組件sdkmanager --install platforms;android-34 build-tools;34.0.0或者直接在Gradle配置里用android.suppressUnsupportedCompileSdk的方式控制版本兼容。7.4 兩端構建通過后的驗證清單構建任務創(chuàng)建完手動觸發(fā)一次拿到構建成功的日志后做以下驗證在CodeHub上修改一次代碼并push確認流水線自動觸發(fā)如果配置了自動觸發(fā)從制品庫下載iOS的.ipa和Android的APK分別安裝到模擬器和真機驗證讓另一位同事從CodeHub重新clone代碼跑一次本地編譯確認新成員環(huán)境也能正常復現(xiàn)檢查構建日志里有沒有warning或非致命錯誤盡量消除我建議至少把這些驗證做全再進行下一步的自動化集成否則環(huán)境層面埋下的雷會在后續(xù)功能迭代中反復炸。8. 寫在最后的個人操作心得做完整套環(huán)境搭建我最想強調的一點是不要小看環(huán)境對齊這件事。代碼托管只是把代碼放到了云上真正的價值在云端構建和協(xié)作流程里而這兩者的基礎就是本地環(huán)境和云端環(huán)境的一致性。如果兩邊版本不一致你每天的工作都會在本地能跑云端報錯的循環(huán)里消耗大量時間。實操了多次之后我現(xiàn)在的習慣是每次本地工具鏈一升級就在云端的構建任務、流水線配置里做一次同步更新同時更新團隊文檔里的環(huán)境對齊清單。不要等到下次構建失敗時再想起來那時候排查成本已經上去了。另一個有價值的體會是文檔比記憶靠譜。我們團隊現(xiàn)在維護了一份標準的入職環(huán)境搭建文檔內容就是這篇文章里講到的流程壓縮版。新人來了照著做基本半天內能把環(huán)境和CI鏈路跑通。如果你也是移動端團隊的負責人我強烈建議把環(huán)境搭建規(guī)范做成文檔讓每個成員按同一套標準來后續(xù)省下的時間絕對值得。 華為云DevCloud與CodeHub實戰(zhàn)：移動端Git配置與環(huán)境對齊指南
1. 初識DevCloud與CodeHub為什么移動端團隊要重構代碼托管鏈路我們團隊之前一直用自建Git服務器托管代碼服務器放在某辦公樓的機房里平時用著還行一旦遇到網絡抖動或者機房斷電整個團隊的提交和拉取就全卡住了。最難受的是iOS和Android兩個端的同學要用不同的工具鏈代碼托管和構建環(huán)境割裂得很厲害每次發(fā)版都要人工協(xié)調半天。后來我們立項做一款新的移動端管理App決定把代碼托管和云端構建整體遷到華為云DevCloud上核心的代碼倉庫放到CodeHub。這件事看起來只是把Git倉庫換個地方放實際操作下來牽扯到的東西比我預想的多得多SSH密鑰怎么配、iOS和Android兩端如何共用一套托管策略、本地環(huán)境怎么和云端構建機對齊、CI/CD流水線怎么串聯(lián)起來。這篇就是整個系列的第一篇專門講Git連接CodeHub以及iOS、Android的本地和云端開發(fā)環(huán)境怎么一步步搭起來。如果你正準備把移動端項目遷到華為云或者剛開始用DevCloud和CodeHub這篇應該能幫你省不少時間。我個人的體會是遷移最怕的不是技術難度而是兩邊環(huán)境不一致。本地是本地云端是云端代碼托管又是中間那一環(huán)任何一環(huán)版本對不上后面跑流水線的時候就會冒出一堆莫名其妙的報錯。所以這篇文章會從代碼托管這條鏈路切入先把Git和CodeHub的連接徹底講透再分別展開iOS和Android這邊的環(huán)境配置最后把云端構建的環(huán)境對齊和常見坑也一并說清楚。1.1 華為云DevCloud到底是什么和CodeHub是什么關系先把這個概念理清楚。華為云DevCloud現(xiàn)在控制臺里也經常看到CodeArts品牌指的是同一套DevOps服務是一個一站式研發(fā)云平臺涵蓋項目管理、代碼托管、編譯構建、部署發(fā)布、流水線等能力。而CodeHub是其中負責代碼托管的模塊本質上就是一個基于Git的云端倉庫服務和GitHub、GitLab屬于同類產品只是它深度集成在華為云的整體生態(tài)里。對于移動端團隊來說CodeHub解決的核心痛點是倉庫不再依賴內網服務器團隊成員在任意網絡環(huán)境都能拉取和推送代碼倉庫權限可以和DevCloud的項目成員體系打通同時代碼倉庫和構建服務天然聯(lián)動后續(xù)做CI/CD的時候不需要額外寫一堆腳本去對接。這里有一個很重要的認知CodeHub不是簡單的云盤版Git倉庫它和DevCloud的流水線、編譯構建任務是聯(lián)動的。你在本地提交代碼到CodeHubCodeHub觸發(fā)Webhook云端構建機拉取最新代碼開始編譯整個鏈條是通的。如果只是把代碼推到遠程倉庫而不用云端構建那這套遷移的意義就打了一半折扣。1.2 為什么我覺得這一步值得單獨寫一篇很多教程上來就直接讓你執(zhí)行git clone忽略了環(huán)境搭建的系統(tǒng)性。但移動端開發(fā)和后端不一樣涉及的本地工具鏈很重iOS必須用macOS加XcodeAndroid需要JDK、Android Studio、SDK、Gradle一大堆。如果只講倉庫配置不講環(huán)境對齊你本地跑得好好的代碼到了云端構建機上大概率編譯不過。另外一個容易被忽略的問題是iOS和Android兩個平臺對Git的使用習慣有差異。iOS端通常直接在Xcode里操作GitAndroid端則習慣用Android Studio的VCS菜單或者命令行。兩端提交代碼時對.gitignore的處理、對二進制文件的管理方式也不同。既然放在同一個CodeHub倉庫下這些差異就必須在環(huán)境搭建階段就統(tǒng)一規(guī)范好。所以我這篇的定位是先搞定代碼托管這一層再搞定兩端環(huán)境這一層兩者的交叉點就是本地Git配置和SSH密鑰。下面我從最基礎的SSH配置開始講這是連接CodeHub的第一道關卡。2. Git與CodeHub建立連接SSH密鑰生成、配置與驗證全程記錄2.1 本地Git環(huán)境準備與版本選擇無論iOS還是Android端第一步都是在本地裝好Git。macOS上我推薦用Homebrew安裝命令是brew install git安裝完檢查版本git --version這里有一個需要注意的細節(jié)macOS自帶的Git版本可能比較老而且Xcode如果更新過系統(tǒng)的Git路徑可能會被Xcode的命令行工具覆蓋導致版本混亂。建議用Homebrew的Git并確保which git指向/usr/local/bin/git或/opt/homebrew/bin/git不要指向/usr/bin/git。Windows端推薦直接裝Git for Windows安裝時選Use Git from the Windows Command Prompt和Checkout as-is, commit as-is這兩個選項前者方便在CMD和PowerShell里直接用git命令后者避免行尾符轉換引發(fā)一堆莫名奇妙的diff。Android端的同學還要裝JDK和Android Studio這個我在第四部分細說這里先保證Git本身是可用的。2.2 SSH密鑰對生成一對密鑰還是兩對密鑰連接CodeHub有兩種方式HTTPS和SSH。HTTPS每次push都要輸入用戶名密碼可以配置credential緩存但團隊協(xié)作時容易出問題SSH則是通過公鑰認證配置好之后push/pull都不需要再輸密碼。移動端團隊我強烈建議用SSH。生成SSH密鑰的命令ssh-keygen -t rsa -b 4096 -C your_emailexample.com -f ~/.ssh/id_rsa_devcloud這里有幾個參數(shù)說明一下-t rsa指定算法雖然現(xiàn)在也支持Ed25519但CodeHub對RSA的兼容性最穩(wěn)妥4096位長度足夠安全-C是注釋建議填你在DevCloud注冊的郵箱方便后期識別-f指定文件名我習慣不以默認的id_rsa命名而是單獨命名為id_rsa_devcloud這樣如果電腦上還有其他Git平臺比如自建GitLab或GitHub的密鑰就不會互相覆蓋生成之后~/.ssh目錄下會出現(xiàn)兩個文件id_rsa_devcloud私鑰和id_rsa_devcloud.pub公鑰。私鑰留在本地公鑰要填到CodeHub后臺。如果你同時維護多個代碼托管平臺我建議在~/.ssh/config里做區(qū)分。示例配置Host codehub HostName codehub.devcloud.huaweicloud.com User git IdentityFile ~/.ssh/id_rsa_devcloud這樣后面git clone時可以直接用gitcodehub:Group/Repo.git這種寫法Git會自動使用對應密鑰。沒有這個配置也不影響功能但配置了之后在多密鑰環(huán)境下會省掉很多麻煩。2.3 公鑰配置到CodeHub后臺與本地驗證登錄華為云DevCloud控制臺進入CodeHub服務在個人設置里找到SSH密鑰管理把id_rsa_devcloud.pub里的內容完整復制粘貼進去保存即可。這個公鑰和你的華為云賬號綁定同一賬號下的所有CodeHub倉庫都能用。然后在本地驗證連通性ssh -T gitcodehub.devcloud.huaweicloud.com第一次連接會提示確認指紋輸入yes回車。如果返回類似于Welcome to CodeHub的歡迎信息說明密鑰配置成功。如果提示權限拒絕Permission denied按順序排查公鑰是否完整復制有沒有多復制空格或者漏掉末尾的郵箱注釋私鑰文件的權限是否過寬運行chmod 600 ~/.ssh/id_rsa_devcloudssh-add -l查看私鑰是否已加載到ssh-agent沒有就執(zhí)行ssh-add ~/.ssh/id_rsa_devcloud這里我要特別提一個坑Windows環(huán)境下如果你用的是Git for Windows自帶的OpenSSH但同時又裝了別的SSH工具可能會遇到公鑰能配但就是連不上的問題大概率是SSH客戶端選擇沖突。解決辦法是在Git for Windows的安裝選項里明確設置Use OpenSSH或者在系統(tǒng)環(huán)境變量里把GIT_SSH指向正確的ssh.exe路徑。2.4 創(chuàng)建CodeHub倉庫并完成首次push在CodeHub后臺新建倉庫填充倉庫名選擇可見范圍私有還是公開。國內團隊項目的代碼倉庫保險起見都選私有同時注意DevCloud里項目的成員權限配置——不是項目成員的人看不到倉庫這一點和GitLab的Group權限模型類似。倉庫創(chuàng)建后CodeHub會給出完整的命令行指引HTTPS和SSH兩種方式都有。我們按SSH的方式操作。以iOS端為例如果項目已經存在本地cd your-ios-project git init git add . git commit -m Initial commit git remote add origin gitcodehub.devcloud.huaweicloud.com:GroupName/RepoName.git git push -u origin masterAndroid端的操作完全一致。這里提醒幾個細節(jié)首次git add .之前務必先把.gitignore寫好。iOS項目至少要忽略Pods/、DerivedData/、*.xcuserstateAndroid項目至少要忽略build/、local.properties、.idea/。這些目錄一旦被提交進去后面再想清理就得用git rm -r --cached麻煩不說還容易誤刪分支命名建議統(tǒng)一用master或mainDevCloud的倉庫默認分支可以在后臺改。后續(xù)如果走Git Flow再按需建develop、release分支首次push的倉庫建議不要太大超過幾百MB時用git gc壓縮一下對象否則網絡不穩(wěn)定時容易push失敗3. iOS本地與云端開發(fā)環(huán)境Xcode、模擬器與構建機的配合3.1 Xcode版本選擇與命令行工具iOS開發(fā)繞不開Xcode。官方渠道是App Store安裝等Xcode下載完再裝Command Line Toolsxcode-select --install裝完后把命令行工具路徑指向Xcode自帶的工具鏈sudo xcode-select -s /Applications/Xcode.app/Contents/Developer然后驗證xcode-select -p這一步看似簡單但我遇到過一個很頭疼的問題Xcode更新到新版本后xcodebuild命令報錯找不到SDK。這個問題的根源是xcode-select的路徑被重置了或者多個Xcode版本并存導致系統(tǒng)指向了錯誤的Developer目錄。所以每次升級Xcode后我都習慣先跑一遍xcode-select -p確認路徑再跑xcodebuild -version確認版本。云端構建這部分華為云DevCloud提供macOS構建機。這里的關鍵點是本地Xcode主版本和云端構建機的Xcode版本必須一致或至少兼容。比如本地用Xcode 15云端也盡量保持在15這個大版本。如果不一致最容易出現(xiàn)的情況是本地編譯鏈接通過提交上去之后云端構建報錯什么SDK版本過低parameter of xxx is unavailable之類看起來像是代碼問題實際是工具鏈版本不一致導致的。DevCloud的構建任務配置頁面里可以選擇構建機類型和Xcode版本這一步一定要和本地對齊。我記過一次很典型的例子A同學本地Xcode 16提交的代碼云端的構建機還停留在Xcode 14結果一跑流水線就報iOS 17 SDK required。當時排查了半小時最后發(fā)現(xiàn)不是代碼問題純粹是版本錯位。3.2 本地模擬器與真機調試的環(huán)境細節(jié)模擬器本身不算復雜但涉及證書簽名的環(huán)節(jié)容易卡人。模擬器構建不需要證書直接CommandR就能跑真機調試需要Apple Development證書和描述文件。這個證書體系對新手來說是第一道坎。實操層面在Xcode的Signing Capabilities面板里勾選Automatically manage signingXcode會自動幫你生成開發(fā)證書和描述文件。但如果你是用CodeHub拉下來的倉庫且項目里的Bundle Identifier和當前開發(fā)者賬號不匹配會自動簽名會失敗。我一般建議確認團隊里每個開發(fā)者在DevCloud項目的成員列表里并且有對應的Apple開發(fā)者賬號權限項目里如果涉及推送、App Group等能力在Apple開發(fā)者后臺提前配好不要提交個人證書和描述文件到Git倉庫用Xcode的自動管理機制代替云端iOS構建時證書的處理方式不同需要把證書和描述文件上傳到DevCloud的證書管理里構建時通過配置關聯(lián)。這個我放到第五節(jié)講流水線時一起說。3.3 使用Xcode連接CodeHub倉庫的操作路徑Xcode內置了Git客戶端在項目初始化的界面上Xcode 15及以上的版本在創(chuàng)建項目時可以選擇源碼控制。如果是已有的項目要通過Xcode連接CodeHub可以在Xcode的Source Control菜單里添加遠程倉庫填入CodeHub的SSH地址。這里有個Xcode使用上的細節(jié)Xcode的Git界面在查看Diff、提交、推送時還算好用但遇到沖突解決時我還是建議切換到命令行或第三方工具。Xcode的沖突解決界面做得比較簡陋多個紛爭并發(fā)時容易點錯導致誤把別人的修改覆蓋掉。比較穩(wěn)妥的工作流是在Xcode里寫代碼、看Diff、做常規(guī)提交切換分支、合并、處理沖突時用命令行工具推送到遠程之前先在命令行看一遍git log和git status另外Xcode項目文件.xcodeproj是結構化目錄Git合并時經常出現(xiàn)項目文件沖突。團隊協(xié)作時最好約定一個規(guī)則同一時間段內盡量不要多人同時修改項目配置比如簽名配置、Target設置這些能避免大量無意義的沖突。4. Android本地與云端開發(fā)環(huán)境Android Studio、Gradle與CodeHub的三角組合4.1 JDK與Android Studio安裝的版本匹配問題Android端的本地環(huán)境搭建第一個坑就是JDK版本。Android Studio新版本如Koala及以后內置了JBRJetBrains Runtime但Gradle構建時仍需要Java環(huán)境。常見的匹配關系大致如下Gradle版本JDK版本要求AGP版本建議7.xJDK 11或177.x8.xJDK 178.x8.5JDK 17或218.5如果不匹配最常見的就是Unsupported class file major version這類報錯。根本原因是Gradle運行時的JDK和編譯字節(jié)碼的JDK不一致。Android Studio自帶JBR但命令行構建時比如在CI環(huán)境里系統(tǒng)默認的java可能是Oracle JDK或者OpenJDK的某個版本?，F(xiàn)在大部分企業(yè)項目的實踐經驗是在項目根目錄的gradle.properties或.java-version文件里固定JDK版本然后確保本地的JAVA_HOME指向正確的路徑。Android Studio安裝完成后還要通過SDK Manager下載對應版本的Android SDK Platform、Build Tools和NDK如果你的項目用C/C代碼。SDK的路徑配置很重要Android Studio默認會寫到用戶目錄下的Android/Sdk這個路徑務必記下來后面配置云端構建時還要用到。4.2 Gradle初始化與項目依賴同步Android項目的構建核心是Gradle。新建項目或從CodeHub拉取項目后Android Studio會自動同步Gradle依賴。但如果是從倉庫拉的老項目大概率會遇到兩個問題Gradle wrapper版本和本地已安裝的Gradle版本不匹配依賴源拉取超時第一個問題的解決辦法是修改gradle/wrapper/gradle-wrapper.properties里的distributionUrl或者直接在Android Studio里調整Gradle JDK版本。第二個問題在實際中更常見經常是國內網絡環(huán)境下默認的Google Maven倉庫拉取慢。常用的做法是在項目級build.gradle里配置阿里云鏡像倉庫buildscript { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/gradle-plugin } } }這個配置我一般建議只在本地開發(fā)環(huán)境加提交代碼時通過git update-index --skip-worktree build.gradle的方式避免誤提交或者干脆在CI環(huán)境里用環(huán)境變量控制鏡像源。原因也很簡單如果所有團隊成員都用自己的鏡像配置可能會出現(xiàn)依賴源不一致、構建結果不一致的情況。4.3 Android Studio的VCS配置與從CodeHub拉取項目Android Studio內置了Git支持首次打開項目后通過VCS菜單可以把本地倉庫切換到CodeHub遠程。操作路徑是VCS Git Remotes添加CodeHub的SSH地址。這里有一個重要的操作習慣Android Studio里右鍵項目文件時會看到很多Git相關的操作但不要用Android Studio的Git去處理項目文件的沖突。Android Studio在合并多個模塊的Gradle腳本時自動合并策略有時候會把兩個不相關的改動強行合并到一起產生邏輯層面的錯誤。一般認為最穩(wěn)妥的Android Git操作順序是在Android Studio里開發(fā)編碼切換到命令行執(zhí)行git pull --rebase拉取遠端最新代碼手動處理沖突后再回Android Studio刷新項目本地編譯通過后再push到CodeHub這樣看似多了一步實際能避免很多Git操作造成的問題。4.4 Android云端構建環(huán)境的認知本質上就是一臺預裝SDK的Linux機器DevCloud的Android構建機本質上是一臺預裝了JDK、Android SDK、Gradle的Linux虛擬機。你在本地能跑通的構建理論上云端也能跑通前提是環(huán)境對齊。這里最容易出問題的點有三個SDK版本本地裝的是API 34云端構建機可能只預裝了API 33編譯時就會報SDK component platforms;android-34 was not found。解決辦法是在流水線構建任務里加上SDK安裝步驟或者通過腳本自動下載對應版本Gradle緩存云端構建機每次構建時如果不是同一臺機器Gradle的依賴緩存可能為空構建耗時明顯拉長。DevCloud構建任務支持配置緩存策略建議開啟簽名配置release包的簽名文件.jks不要放進倉庫本地構建時用local.properties引用簽名路徑云端構建時通過DevCloud的私密參數(shù)下發(fā)我在初期的項目里吃過虧本地release構建一直正常云端一跑就報Key was created with errors排查后發(fā)現(xiàn)是簽名文件被加密后云端構建機上解密生成的臨時文件權限不對。這種問題很隱蔽寫在流水線配置里要注意文件的加密與解密順序。5. 云的流水線配置從代碼提交到自動化構建的核心鏈路5.1 在DevCloud里創(chuàng)建編譯構建任務DevCloud的CI/CD核心是流水線Pipeline構建任務可以單獨配置也可以放在流水線里串聯(lián)。以Android為例最基本的構建任務是從CodeHub拉取代碼執(zhí)行./gradlew assembleDebug產出APK。流程上先在DevCloud控制臺進入編譯構建新建構建任務選擇代碼源為CodeHub選中對應的倉庫和分支選擇構建模板Android有現(xiàn)成的模板會幫你填充Gradle命令和SDK路徑配置構建機類型一般選Linux Docker保存之后手動執(zhí)行一次看構建日志這里有一個很關鍵的點構建任務拉取代碼時用的憑證。DevCloud的構建任務默認使用你創(chuàng)建任務時關聯(lián)的賬號權限但它拉取代碼的憑證是獨立的。如果構建日志里出現(xiàn)Authentication failed不要慌去構建任務的代碼源配置里檢查是否選擇了正確的CodeHub倉庫訪問權限。另一種路徑是你在自己的流水線里寫自定義腳本用git clone命令手動拉取代碼然后執(zhí)行構建命令。這種方式的靈活度最高但你必須自己管理SSH密鑰或HTTPS憑證在構建機上的存放位置稍有不慎就會把密鑰泄露到構建日志里。我建議新手優(yōu)先用DevCloud自帶代碼源配置不要在腳本里手動處理認證。5.2 iOS云端構建的證書管理與描述文件策略iOS云端構建相對Android更繁瑣核心在于證書和描述文件不能像Android那樣簡單用密鑰參數(shù)。DevCloud提供證書管理功能把.p12證書文件和.mobileprovision上傳到云端構建時綁定到對應任務。實操中我發(fā)現(xiàn)以下幾個環(huán)節(jié)是坑點高發(fā)區(qū)證書導出在鑰匙串訪問里導出.p12時注意勾選包含私鑰并設置導出密碼。這個密碼在云端構建配置時要用到描述文件選擇確保描述文件包含的設備列表包含運行真機的設備或者使用App Store類型描述文件。如果描述文件不匹配簽名階段會直接報錯構建命令的選擇xcodebuild的-exportArchive階段要指定ExportOptions.plist這個文件里寫的teamID、method要和證書匹配。我們在實際項目中維護了一個ExportOptions.plist模板放在倉庫里避免每個人本地手寫導出配置構建日志里常見的errSecInternalComponent錯誤大多是證書導入到云端Keychain時權限問題。DevCloud的文檔里會提到構建機鑰匙串權限設置建議仔細閱讀這里不再展開。5.3 流水線串聯(lián)提交觸發(fā)、靜態(tài)檢查與產物歸檔當兩端構建任務都跑通后就可以把它們串到一條流水線里。DevCloud里創(chuàng)建流水線經過這幾個階段代碼提交時自動觸發(fā)在倉庫配置Webhook或者流水線的代碼源綁定CodeHub倉庫每次push自動啟動流水線并行執(zhí)行iOS構建和Android構建在邏輯上相互獨立可以配置成并行階段節(jié)省總耗時靜態(tài)檢查可選DevCloud集成了代碼檢查服務可以加在構建前攔截明顯的編碼規(guī)范問題產物歸檔把生成的.ipa和.apk文件歸檔到DevCloud的軟件發(fā)布庫或制品庫方便測試同學直接下載這里分享一下我對自動化程度的建議不是流水線越復雜越好。早期階段兩端各一條簡單的構建任務加上手動觸發(fā)已經比人工打包進步一大截。等團隊穩(wěn)定了再逐步加自動化觸發(fā)、代碼檢查、自動部署到測試環(huán)境。一上來就配置全自動鏈路維護成本會很高而且出現(xiàn)問題后排查難度大。5.4 云端構建機與本地環(huán)境的一致性維護清單這是一個我強烈建議做成文檔的清單。我們在實際運營中總結出來的一致性維護項包括檢查項本地云端構建機Xcode版本Xcode 15.xXcode 15.xAndroid SDK平臺API 34構建腳本中動態(tài)安裝JDK版本JDK 17JDK 17Gradle版本由wrapper指定使用wrapper簽名方式本地jks文件云端證書管理依賴源海外或鏡像源與本地保持一致這個清單不是一勞永逸的。每次系統(tǒng)升級、工具鏈更新都要重新對齊一輪。特別是Xcode大版本更新后SDK特性變化很大本地一升級云端立刻要跟進否則下一次云端構建就會失敗。6. 環(huán)境搭建避坑實錄版本、超時與權限邊界的經典坑6.1 Xcode升級后xcodebuild路徑錯亂的處理開頭提到過xcode-select的問題再展開講一次具體案例。有一次Xcode從15.2升到15.3之后團隊里幾個iOS開發(fā)同時報告在終端跑xcodebuild時提示找不到這個命令。排查后發(fā)現(xiàn)原因是升級過程中系統(tǒng)把/Library/Developer/CommandLineTools激活成了默認開發(fā)者目錄而xcodebuild實際上在Xcode.app內部。運行sudo xcode-select -s /Applications/Xcode.app/Contents/Developer即可解決。此外如果安裝了多個Xcode版本比如Xcode_14.x和Xcode_15.x并存建議在構建腳本里顯式指定DEVELOPER_DIR環(huán)境變量否則不同終端環(huán)境可能選到不同的Xcode構建結果都會不一樣。這里我給的方案是在項目根目錄維護一個env.sh腳本里面寫好export DEVELOPER_DIR/Applications/Xcode.app/Contents/Developer export JAVA_HOME/path/to/jdk-17每次打開新終端或者進入項目目錄時先source env.sh從源頭避免環(huán)境錯亂。6.2 Gradle依賴下載超時的排查鏈路Android構建最容易出現(xiàn)的經典坑就是依賴下載超時。表現(xiàn)是構建日志里出現(xiàn)類似Could not resolve com.android.tools.build:gradle:8.x.x或Connection timed out。這時候不要急著重試先按順序排查確認distributionUrl對應的Gradle版本能否從網絡正常下載檢查倉庫地址是否可訪問直接在瀏覽器里訪問一下對應URL檢查本機是否有代理或防火墻攔截了相關域名如果用的是鏡像源確認鏡像源同步完整在實際案例里我們遇到過鏡像源只同步了部分模塊導致解析失敗的情況這時候把缺失的倉庫臨時切回Google官方倉庫即可。另外合理配置Gradle離線緩存也能顯著緩解~/.gradle/caches目錄的緩存可以復制到云端構建機的持久化磁盤避免每次構建從零下載。6.3 敏感文件入庫的補救流程經常有同事在配置環(huán)境時臨時改了local.properties提交代碼時不小心把這個文件帶進倉庫。這個文件里通常含有SDK路徑、本地簽名文件路徑等信息不應該進倉庫。補救流程分兩步# 第一步把文件從Git追蹤中移除 git rm --cached local.properties # 第二步加入.gitignore避免再次誤提交 echo local.properties .gitignore git commit -m Remove local.properties from version control但如果這個文件已經被推送到了遠程倉庫光這么做還不夠因為歷史記錄里仍然存在該文件內容。為了徹底移除要用git filter-branch或git filter-repo重寫歷史。這個操作會導致倉庫的commit hash變化如果倉庫已經有多人協(xié)作重寫歷史前必須和團隊成員確認否則其他人的本地分支全部會失聯(lián)。我個人經驗是在項目初期就嚴格把關.gitignore比事后補救成本低得多。團隊里可以做一次代碼評審約定凡是涉及本地環(huán)境信息的文件一律不入庫。6.4 權限邊界與團隊成員協(xié)作的注意事項CodeHub的權限模型里代碼倉庫的訪問權限與DevCloud的項目成員角色綁定常見角色有項目經理、開發(fā)人員、測試人員、瀏覽者等。開發(fā)人員默認有倉庫的push權限測試人員只有只讀權限這一點在配置完權限后要告知每位成員避免出現(xiàn)測試同學想拉代碼卻拉不下來的疑問。還有一個容易忽略的點成員從DevCloud項目里移除后他/她原來的SSH公鑰會立即失效哪怕公鑰還留在CodeHub的個人設置里。這是一個安全設計但如果項目內人員流動頻繁新成員加入后一定要走加入項目的流程而不是單獨添加公鑰后者容易在忘卻后造成權限邊界混亂。7. 一個完整的實操演示從零連接CodeHub到兩端構建通過這部分我以團隊里真實走過的路徑為藍本整理出一份可以直接對照操作的完整流程清單。假設我們的項目叫某跨平臺管理AppiOS和Android兩個端的代碼放在同一個CodeHub倉庫里用不同目錄區(qū)分也可以是兩個獨立倉庫邏輯一致這里以單倉庫為例。7.1 初始化階段本地項目與CodeHub倉庫的關聯(lián)第一步在CodeHub創(chuàng)建一個空倉庫例如mobile-app。創(chuàng)建時選私有初始化時不要勾選生成README和.gitignore保持倉庫為空因為我們本地項目已存在。第二步在項目根目錄建立.gitignore。iOS和Android雙端目錄結構示例# iOS Pods/ DerivedData/ *.xcuserstate xcuserdata/ # Android build/ .gradle/ local.properties .idea/ *.apk *.aab captures/ # 通用 .DS_Store *.log第三步執(zhí)行本地Git初始化并連接遠程git init git add . git commit -m Initial commit git remote add origin gitcodehub.devcloud.huaweicloud.com:YourGroup/mobile-app.git git push -u origin master這個階段遇到最多的問題就是push時提示Permission to XXX denied按第2.3節(jié)的方法排查密鑰配置。等push成功CodeHub網頁端能看到代碼就說明Git連接這一環(huán)徹底打通了。7.2 iOS本地編譯驗證與云端任務創(chuàng)建本地打開Xcode確認能直接編譯運行項目。然后到DevCloud創(chuàng)建iOS構建任務主要內容包括代碼源選擇CodeHub倉庫分支選擇master構建機選擇macOS類型構建模板選擇Xcode相關模板在證書管理里導入.p12和.mobileprovision構建命令選擇xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Release clean archive并指定導出選項這一步容易出的問題構建機型號不同xcworkspace的Pod安裝情況也不同。如果項目使用CocoaPods要確保構建前先執(zhí)行pod install否則workspace無法生成構建直接失敗。7.3 Android本地編譯驗證與云端任務創(chuàng)建Android端同樣先確保本地能跑通./gradlew assembleDebug。然后到DevCloud創(chuàng)建Android構建任務代碼源選擇同一CodeHub倉庫構建機類型選擇Linux構建命令填寫./gradlew clean assembleDebug配置JDK和SDK路徑如果構建時下載依賴慢開啟Gradle緩存這里的關鍵是SDK路徑。DevCloud的Linux構建機預裝了SDK但版本可能不是你需要的。我們的做法是在構建腳本開頭動態(tài)安裝SDK組件sdkmanager --install platforms;android-34 build-tools;34.0.0或者直接在Gradle配置里用android.suppressUnsupportedCompileSdk的方式控制版本兼容。7.4 兩端構建通過后的驗證清單構建任務創(chuàng)建完手動觸發(fā)一次拿到構建成功的日志后做以下驗證在CodeHub上修改一次代碼并push確認流水線自動觸發(fā)如果配置了自動觸發(fā)從制品庫下載iOS的.ipa和Android的APK分別安裝到模擬器和真機驗證讓另一位同事從CodeHub重新clone代碼跑一次本地編譯確認新成員環(huán)境也能正常復現(xiàn)檢查構建日志里有沒有warning或非致命錯誤盡量消除我建議至少把這些驗證做全再進行下一步的自動化集成否則環(huán)境層面埋下的雷會在后續(xù)功能迭代中反復炸。8. 寫在最后的個人操作心得做完整套環(huán)境搭建我最想強調的一點是不要小看環(huán)境對齊這件事。代碼托管只是把代碼放到了云上真正的價值在云端構建和協(xié)作流程里而這兩者的基礎就是本地環(huán)境和云端環(huán)境的一致性。如果兩邊版本不一致你每天的工作都會在本地能跑云端報錯的循環(huán)里消耗大量時間。實操了多次之后我現(xiàn)在的習慣是每次本地工具鏈一升級就在云端的構建任務、流水線配置里做一次同步更新同時更新團隊文檔里的環(huán)境對齊清單。不要等到下次構建失敗時再想起來那時候排查成本已經上去了。另一個有價值的體會是文檔比記憶靠譜。我們團隊現(xiàn)在維護了一份標準的入職環(huán)境搭建文檔內容就是這篇文章里講到的流程壓縮版。新人來了照著做基本半天內能把環(huán)境和CI鏈路跑通。如果你也是移動端團隊的負責人我強烈建議把環(huán)境搭建規(guī)范做成文檔讓每個成員按同一套標準來后續(xù)省下的時間絕對值得。