官方出品丨Cocos Creator 3.x 升級(jí)指南，常見(jiàn)問(wèn)題一文全解

Cocos Creator 3.x 作為 Creator 的主力版本，經(jīng)過(guò)引擎組的不斷努力，目前已經(jīng)逐漸趨于成熟與穩(wěn)定，可以為開(kāi)發(fā)者提供更好的服務(wù)。現(xiàn)為開(kāi)發(fā)者提供升級(jí) Cocos Creator 2.x 到 3.x 的詳細(xì)方式，含項(xiàng)目升級(jí)、代碼升級(jí)、材質(zhì)升級(jí)、常見(jiàn)問(wèn)題及解決。

注意： 目前我們不建議開(kāi)發(fā)中的項(xiàng)目，特別是即將上線的項(xiàng)目強(qiáng)升 v3.x。

項(xiàng)目升級(jí)

目前針對(duì) v2.4.3 以下的版本，我們推薦先將舊項(xiàng)目升級(jí)到 v2.4.3 或以上版本，然后再導(dǎo)入到 v3.x，否則無(wú)法確保導(dǎo)入結(jié)果的正確性。

因此升級(jí)的第一步是先將舊項(xiàng)目升級(jí)到 v2.4.3 或以上版本，再對(duì)舊項(xiàng)目進(jìn)行排查，檢查是否有出現(xiàn)問(wèn)題。關(guān)于更多 v2.4.x 的升級(jí)問(wèn)題可以查看 [v2.4 升級(jí)指南]。

在成功升級(jí)為 v2.4.3 或以上版本后，接下來(lái)可以在 Cocos Dashboard 中新建一個(gè)空項(xiàng)目并打開(kāi)。如下圖：

update-dashboard

然后便可以在新建的空項(xiàng)目中通過(guò) Creator 的導(dǎo)入插件對(duì)項(xiàng)目進(jìn)行升級(jí)。

開(kāi)發(fā)者只需要點(diǎn)擊主菜單中的 文件 -> 導(dǎo)入 Cocos Creator 2.x 項(xiàng)目。

import-menu

然后在彈出的文件瀏覽對(duì)話框中選擇 v2.x 項(xiàng)目的根目錄。

import-menu

v2.x 項(xiàng)目中所有的資源便會(huì)自動(dòng)呈現(xiàn)在彈出的 導(dǎo)入 Cocos Creator 2.x 項(xiàng)目 面板中，開(kāi)發(fā)者可以再次確認(rèn)要導(dǎo)入的資源，然后點(diǎn)擊面板右下角的 導(dǎo)入 按鈕完成導(dǎo)入。若開(kāi)發(fā)者想要切換導(dǎo)入的 v2.x 項(xiàng)目，點(diǎn)擊下圖中的搜索圖標(biāo)按鈕，即可重新選擇項(xiàng)目。

import-project

面板左下角的 使用說(shuō)明 按鈕可跳轉(zhuǎn)到導(dǎo)入項(xiàng)目插件的 GitHub 倉(cāng)庫(kù)，用于 [更新導(dǎo)入插件] 或者提交反饋。

選擇導(dǎo)入之后，項(xiàng)目就已經(jīng)被生成到之前新建的空項(xiàng)目中，并且 不會(huì)改動(dòng) 到原有的舊項(xiàng)目。項(xiàng)目的 資源部分 就已經(jīng)成功導(dǎo)入啦。

代碼升級(jí)

對(duì)于項(xiàng)目的代碼，Creator 的導(dǎo)入插件提供了很好的代碼遷移輔助。如果開(kāi)發(fā)者的舊項(xiàng)目是使用 JavaScript 進(jìn)行開(kāi)發(fā)的，那么導(dǎo)入插件會(huì)先將 JavaScript 轉(zhuǎn)換成 TypeScript，再統(tǒng)一進(jìn)行代碼的輔助遷移。

例如下面的一段代碼：

// AudioController.ts
@ccclass("AudioController")
export class AudioController extends Component { 
    
    @property(cc.AudioSource)
    public audioSource: cc.AudioSource = null!;
    private _isPlay:boolean = false;

    play () {
        this.audioSource.play();
        this._isPlay =true;
    }

    pause () {
        this.audioSource.pause();
        this._isPlay =false;
    }
}

由于各個(gè)項(xiàng)目代碼的復(fù)雜度與寫法的差異性，目前導(dǎo)入插件對(duì)代碼的升級(jí)僅添加 組件類型聲明、屬性聲明及函數(shù)聲明，而組件在場(chǎng)景中的引用都會(huì)得到 保留，并且函數(shù)內(nèi)部的代碼在遷移后會(huì)以 注釋 的形式保留。

在經(jīng)過(guò)導(dǎo)入插件的代碼 輔助遷移 之后，結(jié)果如下圖所示。最下方的注釋部分是項(xiàng)目的原代碼，方便開(kāi)發(fā)者在進(jìn)行代碼升級(jí)時(shí)作為參考：

// AudioController.ts
import { _decorator, AudioSource } from 'cc';
@ccclass("AudioController")
export class AudioController extends Component { 
    
    @property(AudioSource)
    public audioSource: AudioSource = null!;
    private _isPlay:boolean = false;

    play () {
        //this.audioSource.play();
        //  this._isPlay =true;
    }

    pause () {
        //this.audioSource.pause();
        // this._isPlay =false;
    }
}

/**
 * 注意：原來(lái)的腳本已經(jīng)注釋掉了，由于腳本中的大量更改，轉(zhuǎn)換過(guò)程中可能會(huì)丟失，需要手動(dòng)轉(zhuǎn)換
 */

// // AudioController.ts
// @ccclass("AudioController")
// export class AudioController extends Component { 
    
//      @property(cc.AudioSource)
    // public audioSource: cc.AudioSource = null!;
    // private _isPlay:boolean = false;

    // play () {
    //     this.audioSource.play();
    //     this._isPlay =true;
    // }

    // pause () {
    //     this.audioSource.pause();
    //     this._isPlay =false;
    // }
// }

通過(guò)這樣的方式，減輕開(kāi)發(fā)者的升級(jí)難度，為開(kāi)發(fā)者提供更好的升級(jí)方式。

需要注意的是：

• 如果是從 JavaScript 轉(zhuǎn)換為 TypeScript 的。需要在 TypeScript 中聲明 所有屬性 并設(shè)置默認(rèn)值。

• 如果 屬性檢查器 面板數(shù)據(jù)丟失，則需要檢查屬性類型是否與 v2.x 相同。

• 如果 JavaScript 代碼使用外部類型，TypeScript 會(huì)提示：通過(guò)導(dǎo)入外部源文件或聲明進(jìn)行修復(fù)。

關(guān)于更多將代碼從 JavaScript 升級(jí)到 TypeScript 問(wèn)題和 Cocos Creator v3.x 中 TypeScript 的使用問(wèn)題，可以在[3.0 TypeScript 問(wèn)題答疑及經(jīng)驗(yàn)分享]中進(jìn)行了解。

材質(zhì)升級(jí)

除了代碼升級(jí)以外，目前 Effect 材質(zhì)資源內(nèi)的 Shader 代碼還無(wú)法被自動(dòng)升級(jí)，需要大家根據(jù)升級(jí)文檔來(lái)手動(dòng)升級(jí)。具體請(qǐng)參考：

Cocos Creator 2.x 的材質(zhì)升級(jí)到 v3.0 的注意事項(xiàng)：

https://docs.cocos.com/creator/3.1/manual/zh/material-system/effect-2.x-to-3.0.html

Cocos Creator 3.0 的材質(zhì)升級(jí)到 v3.1 的注意事項(xiàng)：

https://docs.cocos.com/creator/3.1/manual/zh/material-system/Material-upgrade-documentation-for-v3.0-to-v3.1.html

常見(jiàn)問(wèn)題（FAQ）

• 正常的綁定組件定義等一些操作，會(huì)導(dǎo)致 Visual Studio Code 爆紅

注意： 我們更推薦開(kāi)發(fā)者采用嚴(yán)格模式，進(jìn)行書寫代碼。

• Action 動(dòng)作全都失效

• 修改 2D 節(jié)點(diǎn)的 size 和 anchor 不生效

    const uiTrans = node.getComponent(UITransform)!;
    uiTrans.anchorX = 0.5;
    uiTrans.setContentSize(size);

• 修改 2D 節(jié)點(diǎn)的 color 不生效

    const uiColor = node.getComponent(Sprite)!;
    uiColor.color = color(255,255,255);

• 修改 2D 節(jié)點(diǎn)的 skew 不生效

• 無(wú)法獲取分組，但 Creator 的項(xiàng)目設(shè)置中仍有分組設(shè)置

update-setting

• 通過(guò) zIndex 設(shè)置同級(jí)節(jié)點(diǎn)失效

• 通過(guò) getComponent() 無(wú)法獲取到節(jié)點(diǎn)上掛載的腳本

• 在 resources 文件夾下的圖片使用動(dòng)態(tài)加載提示找不到

    resources.load("testAssets/image/spriteFrame", SpriteFrame, (err, spriteFrame) => {
    this.node.getComponent(Sprite).spriteFrame = spriteFrame;
});

• 物體產(chǎn)生物理碰撞之后，原有的物理碰撞回調(diào)沒(méi)有了

    let collider = this.getComponent(Collider2D);
    if (collider) {
        //只在兩個(gè)碰撞體開(kāi)始接觸時(shí)被調(diào)用一次
        collider.on(Contact2DType.BEGIN_CONTACT, this.onBeginContact, this);
        // 只在兩個(gè)碰撞體結(jié)束接觸時(shí)被調(diào)用一次
        collider.on(Contact2DType.END_CONTACT, this.onEndContact, this);
        // 每次將要處理碰撞體接觸邏輯時(shí)被調(diào)用
        collider.on(Contact2DType.PRE_SOLVE, this.onPreSolve, this);
         // 每次處理完碰撞體接觸邏輯時(shí)被調(diào)用
        collider.on(Contact2DType.POST_SOLVE, this.onPostSolve, this);
        }
});

• 升級(jí)之后，物理碰撞分組不見(jiàn)了

• 音頻 audioEngine 接口失效，無(wú)法播放音樂(lè)

注意： 如果設(shè)置成常駐節(jié)點(diǎn)需要注意一個(gè)問(wèn)題：常駐節(jié)點(diǎn)在切場(chǎng)景時(shí)會(huì)暫停音樂(lè)，需要在 onEnable 中繼續(xù)播放（之后會(huì)在引擎?zhèn)冉鉀Q這個(gè)問(wèn)題）。

• 出現(xiàn) Button 按鈕無(wú)法點(diǎn)擊的問(wèn)題

• 升級(jí)后進(jìn)行腳本修改后，編輯器卡死

結(jié)語(yǔ)

上述問(wèn)題只是一些常見(jiàn)問(wèn)題的記錄，如果遇到其它問(wèn)題，可以建立 [issue] 給我們,也可以附上詳細(xì)的復(fù)現(xiàn)步驟及報(bào)錯(cuò)信息到[論壇]反饋。更多升級(jí)問(wèn)題及 API 的廢棄更改等，可參考官方文檔 [v3.0升級(jí)指南]。

參考鏈接：

[v2.4 升級(jí)指南]：

https://docs.cocos.com/creator/manual/zh/release-notes/

[更新導(dǎo)入插件]：

https://github.com/cocos-creator/plugin-import-2.x/blob/main/README.md

[快上車 3D GitHub]：

https://github.com/cocos-creator/tutorial-taxi-game

[快上車 3D Gitee]：

https://gitee.com/mirrors_cocos-creator/tutorial-taxi-game

[3.0 TypeScript 問(wèn)題答疑及經(jīng)驗(yàn)分享]：

https://forum.cocos.org/t/topic/106995

[插件升級(jí)]：

https://github.com/cocos-creator/plugin-import-2.x

[issue]：

https://github.com/cocos-creator/plugin-import-2.x/issues/new

[論壇]：

https://forum.cocos.org/

[v3.0升級(jí)指南]：

https://docs.cocos.com/creator/3.0/manual/zh/release-notes/upgrade-guide-v3.0.html

點(diǎn)擊【閱讀原文】查看 Cocos Creator 3.0 升級(jí)指南官方文檔。