Cocos Creator 远程资源加载完全指南：动态下载、缓存管理与 XML 解析实战

2018-08-26

引言

在现代游戏开发中，热更新和动态资源加载已成为标配功能。无论是减少首包体积、实现皮肤动态更新，还是加载用户生成的内容，都离不开远程资源加载技术。Cocos Creator 提供了强大的资源加载系统，支持从远程 URL 动态加载图片、音频、JSON、XML 等各类资源。本文将详细介绍 Cocos Creator 远程资源加载的完整方案，包括基础加载方法、缓存策略、加载队列管理，以及 XML 数据解析实战。

Cocos Creator 资源加载系统概览

加载管线架构

┌─────────────────────────────────────────────────────────────────────┐
│                  Cocos Creator 资源加载管线                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  cc.loader.load(url, callback)                                      │
│         │                                                            │
│         ▼                                                            │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐       │
│  │   URL 解析   │────►│   缓存检查   │────►│   下载请求   │       │
│  │              │     │              │     │              │       │
│  └──────────────┘     └──────────────┘     └──────────────┘       │
│                              │                    │                 │
│                              │ 命中缓存            │ 下载完成         │
│                              ▼                    ▼                 │
│                       ┌──────────────┐     ┌──────────────┐       │
│                       │ 直接返回缓存  │     │  资源解析    │       │
│                       │   资源       │     │  (图片/JSON) │       │
│                       └──────────────┘     └──────┬───────┘       │
│                                                    │                │
│                                                    ▼                │
│                                             ┌──────────────┐      │
│                                             │  存入缓存    │      │
│                                             │  回调结果    │      │
│                                             └──────────────┘      │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

支持的资源类型

资源类型	URL 扩展名	加载结果类型	说明
图片纹理	.png, .jpg, .webp	cc.Texture2D	可用于 SpriteFrame
音频	.mp3, .ogg, .wav	cc.AudioClip	音效和背景音乐
文本	.txt, .xml, .json	string	原始文本内容
JSON	.json	object	解析后的对象
字体	.ttf, .fnt	cc.Font	动态字体或位图字体

基础远程加载方法

加载远程图片

const { ccclass, property } = cc._decorator;

@ccclass
export default class RemoteImageLoader extends cc.Component {

    @property(cc.Sprite)
    targetSprite: cc.Sprite = null;

    @property
    remoteUrl: string = "https://example.com/images/bg1.jpg";

    /**
     * 加载远程图片并设置到 Sprite
     */
    loadRemoteImage() {
        const url = this.remoteUrl;

        cc.loader.load(url, (err, texture) => {
            if (err) {
                cc.error('Failed to load remote image:', err);
                return;
            }

            // 创建 SpriteFrame
            const spriteFrame = new cc.SpriteFrame(texture);

            // 设置到 Sprite 组件
            if (this.targetSprite) {
                // 保留原有尺寸（可选）
                const originalWidth = this.targetSprite.node.width;
                const originalHeight = this.targetSprite.node.height;

                this.targetSprite.spriteFrame = spriteFrame;

                // 恢复原有尺寸（如果不需要自适应）
                this.targetSprite.node.width = originalWidth;
                this.targetSprite.node.height = originalHeight;
            }

            cc.log('Remote image loaded successfully');
        });
    }
}

带加载状态的处理

@ccclass
export default class SmartImageLoader extends cc.Component {

    @property(cc.Sprite)
    targetSprite: cc.Sprite = null;

    @property(cc.Node)
    loadingNode: cc.Node = null;    // 加载动画节点

    @property(cc.Node)
    errorNode: cc.Node = null;      // 错误提示节点

    private _isLoading: boolean = false;

    /**
     * 智能加载远程图片（带状态管理）
     */
    loadImage(url: string) {
        if (this._isLoading) {
            cc.warn('Another image is being loaded');
            return;
        }

        this._isLoading = true;
        this.showLoadingState();

        cc.loader.load(url, (err, texture) => {
            this._isLoading = false;

            if (err) {
                this.showErrorState();
                cc.error('Image load failed:', err);
                return;
            }

            this.showSuccessState(texture);
        });
    }

    private showLoadingState() {
        if (this.loadingNode) this.loadingNode.active = true;
        if (this.errorNode) this.errorNode.active = false;
        if (this.targetSprite) this.targetSprite.node.active = false;
    }

    private showErrorState() {
        if (this.loadingNode) this.loadingNode.active = false;
        if (this.errorNode) this.errorNode.active = true;
    }

    private showSuccessState(texture: cc.Texture2D) {
        if (this.loadingNode) this.loadingNode.active = false;
        if (this.errorNode) this.errorNode.active = false;

        if (this.targetSprite) {
            this.targetSprite.node.active = true;
            this.targetSprite.spriteFrame = new cc.SpriteFrame(texture);
        }
    }
}

加载远程 JSON 数据

/**
 * 加载远程配置数据
 */
loadRemoteConfig(configUrl: string) {
    cc.loader.load(configUrl, (err, asset) => {
        if (err) {
            cc.error('Config load failed:', err);
            return;
        }

        // asset 已经是解析后的对象
        const config = asset;
        cc.log('Config loaded:', JSON.stringify(config));

        // 应用配置
        this.applyConfig(config);
    });
}

XML 数据解析实战

在游戏开发中，XML 常用于地图数据（Tiled Map）、配置文件、UI 布局等场景。Cocos Creator 加载 XML 文件后会返回原始文本，需要手动解析。

DOMParser 解析 XML

/**
 * 加载并解析 TiledMap 的 XML 数据
 */
loadTiledMapData(mapUrl: string) {
    cc.loader.load(mapUrl, (err, assets) => {
        if (err) {
            cc.error('Map load failed:', err);
            return;
        }

        // assets 是 XML 文本字符串
        const xmlText = assets;

        // 使用 DOMParser 解析 XML
        const parser = new DOMParser();
        const xmlDoc = parser.parseFromString(xmlText, 'text/xml');

        // 解析 tileset 信息
        this.parseTileset(xmlDoc);

        // 解析图层信息
        this.parseLayers(xmlDoc);
    });
}

/**
 * 解析 tileset 数据
 */
private parseTileset(xmlDoc: XMLDocument) {
    const tilesets = xmlDoc.getElementsByTagName('tileset');

    for (let i = 0; i < tilesets.length; i++) {
        const tileset = tilesets[i];
        const firstGid = tileset.getAttribute('firstgid');
        const name = tileset.getAttribute('name');
        const tileWidth = tileset.getAttribute('tilewidth');
        const tileHeight = tileset.getAttribute('tileheight');

        cc.log(`Tileset: ${name}, firstgid=${firstGid}, tileSize=${tileWidth}x${tileHeight}`);

        // 解析 image 标签
        const images = tileset.getElementsByTagName('image');
        if (images.length > 0) {
            const imageSource = images[0].getAttribute('source');
            const imageWidth = images[0].getAttribute('width');
            const imageHeight = images[0].getAttribute('height');

            cc.log(`Image source: ${imageSource}, size=${imageWidth}x${imageHeight}`);

            // 加载图片资源
            this.loadTilesetImage(imageSource);
        }
    }
}

/**
 * 解析图层数据
 */
private parseLayers(xmlDoc: XMLDocument) {
    const layers = xmlDoc.getElementsByTagName('layer');

    for (let i = 0; i < layers.length; i++) {
        const layer = layers[i];
        const name = layer.getAttribute('name');
        const width = layer.getAttribute('width');
        const height = layer.getAttribute('height');

        cc.log(`Layer: ${name}, size=${width}x${height}`);

        // 解析图层数据
        const data = layer.getElementsByTagName('data')[0];
        if (data) {
            const encoding = data.getAttribute('encoding');
            cc.log(`Data encoding: ${encoding}`);
        }
    }
}

/**
 * 加载 tileset 图片
 */
private loadTilesetImage(imagePath: string) {
    const baseUrl = 'https://example.com/resources/tiledMap/bg/';
    const fullUrl = baseUrl + imagePath;

    cc.loader.load(fullUrl, (err, texture) => {
        if (err) {
            cc.error('Tileset image load failed:', err);
            return;
        }

        // 创建 SpriteFrame 用于地图渲染
        const spriteFrame = new cc.SpriteFrame(texture);
        this.onTilesetLoaded(spriteFrame);
    });
}

通用 XML 解析工具类

/**
 * XML 解析工具类
 */
export class XMLParser {

    /**
     * 解析 XML 字符串为对象
     */
    static parse(xmlString: string): any {
        const parser = new DOMParser();
        const xmlDoc = parser.parseFromString(xmlString, 'text/xml');

        // 检查解析错误
        const parseError = xmlDoc.getElementsByTagName('parsererror');
        if (parseError.length > 0) {
            throw new Error('XML parse error');
        }

        return this.nodeToObject(xmlDoc.documentElement);
    }

    /**
     * 将 XML 节点递归转换为对象
     */
    private static nodeToObject(node: Element): any {
        const result: any = {};

        // 解析属性
        if (node.attributes && node.attributes.length > 0) {
            for (let i = 0; i < node.attributes.length; i++) {
                const attr = node.attributes[i];
                result[attr.name] = attr.value;
            }
        }

        // 解析子节点
        if (node.childNodes && node.childNodes.length > 0) {
            for (let i = 0; i < node.childNodes.length; i++) {
                const child = node.childNodes[i];

                if (child.nodeType === Node.TEXT_NODE) {
                    const text = child.textContent.trim();
                    if (text) {
                        result._text = text;
                    }
                } else if (child.nodeType === Node.ELEMENT_NODE) {
                    const childName = child.nodeName;
                    const childObj = this.nodeToObject(child as Element);

                    if (result[childName]) {
                        // 同名节点转为数组
                        if (!Array.isArray(result[childName])) {
                            result[childName] = [result[childName]];
                        }
                        result[childName].push(childObj);
                    } else {
                        result[childName] = childObj;
                    }
                }
            }
        }

        return result;
    }

    /**
     * 获取节点属性值
     */
    static getAttribute(node: Element, name: string, defaultValue: string = ''): string {
        return node.getAttribute(name) || defaultValue;
    }

    /**
     * 获取子节点列表
     */
    static getChildren(parent: Element, tagName: string): HTMLCollectionOf<Element> {
        return parent.getElementsByTagName(tagName);
    }
}

加载队列与并发管理

批量资源加载器

const { ccclass } = cc._decorator;

interface LoadTask {
    url: string;
    type: typeof cc.Asset;
    onProgress?: (progress: number) => void;
    onComplete?: (err: Error, asset: any) => void;
}

@ccclass
export default class BatchResourceLoader {

    private static _instance: BatchResourceLoader = null;

    static getInstance(): BatchResourceLoader {
        if (!this._instance) {
            this._instance = new BatchResourceLoader();
        }
        return this._instance;
    }

    private _maxConcurrent: number = 3;  // 最大并发数
    private _queue: LoadTask[] = [];
    private _running: number = 0;
    private _cache: Map<string, any> = new Map();

    /**
     * 添加加载任务
     */
    load(url: string, type: typeof cc.Asset, callback?: (err: Error, asset: any) => void) {
        // 检查缓存
        if (this._cache.has(url)) {
            callback?.(null, this._cache.get(url));
            return;
        }

        // 添加到队列
        this._queue.push({
            url,
            type,
            onComplete: callback
        });

        this._processQueue();
    }

    /**
     * 批量加载资源
     */
    loadBatch(tasks: { url: string; type: typeof cc.Asset }[],
              onProgress?: (completed: number, total: number) => void,
              onComplete?: (results: Map<string, any>) => void) {

        const total = tasks.length;
        let completed = 0;
        const results = new Map<string, any>();

        tasks.forEach(task => {
            this.load(task.url, task.type, (err, asset) => {
                completed++;

                if (!err) {
                    results.set(task.url, asset);
                }

                onProgress?.(completed, total);

                if (completed >= total) {
                    onComplete?.(results);
                }
            });
        });
    }

    /**
     * 处理加载队列
     */
    private _processQueue() {
        while (this._running < this._maxConcurrent && this._queue.length > 0) {
            const task = this._queue.shift();
            if (!task) continue;

            this._running++;

            cc.loader.load(task.url, (err, asset) => {
                this._running--;

                if (!err && asset) {
                    this._cache.set(task.url, asset);
                }

                task.onComplete?.(err, asset);
                this._processQueue();
            });
        }
    }

    /**
     * 获取缓存的资源
     */
    getFromCache(url: string): any {
        return this._cache.get(url);
    }

    /**
     * 释放缓存的资源
     */
    release(url: string) {
        const asset = this._cache.get(url);
        if (asset) {
            cc.loader.release(url);
            this._cache.delete(url);
        }
    }

    /**
     * 释放所有缓存
     */
    releaseAll() {
        this._cache.forEach((asset, url) => {
            cc.loader.release(url);
        });
        this._cache.clear();
    }
}

缓存策略与内存管理

自定义缓存管理器

const { ccclass } = cc._decorator;

interface CacheEntry {
    asset: any;
    lastAccessed: number;
    accessCount: number;
}

@ccclass
export default class ResourceCacheManager {

    private static _instance: ResourceCacheManager = null;
    static getInstance(): ResourceCacheManager {
        if (!this._instance) {
            this._instance = new ResourceCacheManager();
        }
        return this._instance;
    }

    private _cache: Map<string, CacheEntry> = new Map();
    private _maxSize: number = 50;           // 最大缓存数量
    private _maxMemoryMB: number = 100;      // 最大内存占用（MB）
    private _expireTime: number = 300000;    // 过期时间（5分钟）

    /**
     * 添加资源到缓存
     */
    add(url: string, asset: any) {
        // 如果缓存已满，清理最久未使用的资源
        if (this._cache.size >= this._maxSize) {
            this._evictLRU();
        }

        this._cache.set(url, {
            asset,
            lastAccessed: Date.now(),
            accessCount: 1
        });
    }

    /**
     * 从缓存获取资源
     */
    get(url: string): any {
        const entry = this._cache.get(url);
        if (entry) {
            entry.lastAccessed = Date.now();
            entry.accessCount++;
            return entry.asset;
        }
        return null;
    }

    /**
     * 检查资源是否在缓存中
     */
    has(url: string): boolean {
        const entry = this._cache.get(url);
        if (!entry) return false;

        // 检查是否过期
        if (Date.now() - entry.lastAccessed > this._expireTime) {
            this.remove(url);
            return false;
        }

        return true;
    }

    /**
     * 移除缓存中的资源
     */
    remove(url: string) {
        const entry = this._cache.get(url);
        if (entry) {
            cc.loader.release(url);
            this._cache.delete(url);
        }
    }

    /**
     * 清理最久未使用的资源（LRU 策略）
     */
    private _evictLRU() {
        let oldestUrl: string = null;
        let oldestTime: number = Infinity;

        this._cache.forEach((entry, url) => {
            if (entry.lastAccessed < oldestTime) {
                oldestTime = entry.lastAccessed;
                oldestUrl = url;
            }
        });

        if (oldestUrl) {
            this.remove(oldestUrl);
        }
    }

    /**
     * 清理过期资源
     */
    cleanExpired() {
        const now = Date.now();
        const toRemove: string[] = [];

        this._cache.forEach((entry, url) => {
            if (now - entry.lastAccessed > this._expireTime) {
                toRemove.push(url);
            }
        });

        toRemove.forEach(url => this.remove(url));
    }

    /**
     * 获取缓存统计信息
     */
    getStats() {
        return {
            size: this._cache.size,
            maxSize: this._maxSize,
            entries: Array.from(this._cache.keys())
        };
    }
}

常见问题与解决方案

跨域问题（CORS）

/**
 * 处理远程图片跨域问题
 * 服务器需要设置响应头：Access-Control-Allow-Origin: *
 */
loadCrossOriginImage(url: string) {
    // 确保 URL 支持 CORS
    cc.loader.load({ url: url, type: 'png' }, (err, texture) => {
        if (err) {
            // CORS 错误处理
            if (err.message && err.message.includes('CORS')) {
                cc.error('CORS policy blocked the request');
                // 显示占位图
                this.showPlaceholder();
            }
            return;
        }
        // 使用纹理...
    });
}

加载超时处理

/**
 * 带超时的资源加载
 */
loadWithTimeout(url: string, timeoutMs: number = 10000): Promise<any> {
    return new Promise((resolve, reject) => {
        const timer = setTimeout(() => {
            reject(new Error('Load timeout'));
        }, timeoutMs);

        cc.loader.load(url, (err, asset) => {
            clearTimeout(timer);
            if (err) {
                reject(err);
            } else {
                resolve(asset);
            }
        });
    });
}

总结

Cocos Creator 远程资源加载的核心要点：

基础加载：使用 cc.loader.load(url, callback) 加载远程图片、JSON、文本等资源
状态管理：封装加载器管理 loading、success、error 三种状态
XML 解析：使用 DOMParser 解析 XML 数据，通过 getElementsByTagName 和 getAttribute 提取信息
并发控制：使用队列管理批量加载任务，限制最大并发数避免网络拥塞
缓存策略：实现 LRU 缓存管理器，控制内存占用和缓存过期
异常处理：处理跨域错误、加载超时、网络断开等异常情况

通过合理的资源加载和缓存策略，可以显著减少包体大小，提升游戏加载速度，实现灵活的热更新机制。

游戏开发Cocos Creator

引言