Aspose.3D FOSS
TypeScript
Hướng dẫn khắc phục sự cố

Hướng dẫn khắc phục sự cố

Trang này đề cập đến các lỗi phổ biến nhất gặp phải khi sử dụng @aspose/3d trong các dự án TypeScript và Node.js, kèm theo giải thích nguyên nhân gốc và các giải pháp đã được xác minh.

Lỗi giải quyết mô-đun

Error: Cannot find module '@aspose/3d/formats/obj'

Nguyên nhân gốc: Chiến lược giải quyết mô-đun của TypeScript không hỗ trợ xuất khẩu sub‑path kiểu Node.js (exports trong package.json) trừ khi moduleResolution được đặt thành node hoặc node16.

Sửa lỗi: Đặt moduleResolution thành "node" trong dự án của bạn tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true
  }
}

Nếu bạn đang sử dụng TypeScript 5.x với "module": "node16" hoặc "module": "nodenext", hãy sử dụng "moduleResolution": "node16" để khớp.

SyntaxError: Cannot use import statement in a module

Nguyên nhân gốc: Mã JavaScript đã biên dịch đang được chạy với require() ngữ nghĩa nhưng đầu ra chứa ES module import cú pháp; điều này xảy ra khi module được đặt thành es2020 hoặc esnext nhưng môi trường chạy Node.js mong đợi CommonJS.

Khắc phục:Sử dụng "module": "commonjs" trong tsconfig.json và chạy các tệp đã biên dịch .js tệp với node trực tiếp:

{
  "compilerOptions": {
    "module": "commonjs",
    "outDir": "./dist"
  }
}

Sau đó biên dịch và chạy:

npx tsc
node dist/main.js

Error: Cannot find module '@aspose/3d'

Nguyên nhân gốc: Gói chưa được cài đặt, hoặc node_modules đã lỗi thời.

Sửa:

npm install @aspose/3d

Xác minh việc cài đặt:

node -e "const { Scene } = require('@aspose/3d'); console.log('OK', new Scene().constructor.name);"

Cảnh trống sau khi tải

Cảnh được tải nhưng rootNode.childNodes trống

Nguyên nhân gốc (1):Định dạng tệp đặt tất cả hình học trực tiếp lên rootNode.entity thay vì là các nút con. Điều này thường gặp với các tệp STL một lưới duy nhất.

Chẩn đoán:

import { Scene, Mesh } from '@aspose/3d';

const scene = new Scene();
scene.open('model.stl');

// Check rootNode directly
if (scene.rootNode.entity) {
    console.log(`Root entity: ${scene.rootNode.entity.constructor.name}`);
}
console.log(`Child count: ${scene.rootNode.childNodes.length}`);

Sửa: Duyệt bắt đầu từ scene.rootNode bản thân nó, không chỉ các nút con của nó:

function visit(node: any): void {
    if (node.entity instanceof Mesh) {
        const m = node.entity as Mesh;
        console.log(`Mesh: ${m.controlPoints.length} vertices`);
    }
    for (const child of node.childNodes) {
        visit(child);
    }
}
visit(scene.rootNode);

Nguyên nhân gốc (2): Đường dẫn tệp sai hoặc tệp có kích thước bằng 0 byte. Kiểm tra xem tệp có tồn tại và không rỗng trước khi gọi open().

import * as fs from 'fs';

const path = 'model.obj';
if (!fs.existsSync(path)) throw new Error(`File not found: ${path}`);
const stat = fs.statSync(path);
if (stat.size === 0) throw new Error(`File is empty: ${path}`);

Danh sách vật liệu trống sau khi tải OBJ

Nguyên nhân gốc: Việc tải vật liệu bị tắt mặc định trong ObjLoadOptions. Thư viện tải hình học mà không đọc .mtl tệp phụ.

Sửa: Đặt enableMaterials = true:

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const scene = new Scene();
const opts = new ObjLoadOptions();
opts.enableMaterials = true;
scene.open('model.obj', opts);

Cũng đảm bảo rằng .mtl tệp nằm trong cùng thư mục với .obj tệp, vì thư viện giải quyết nó tương đối với .obj đường dẫn.

Lỗi Định dạng và I/O

openFromBuffer báo lỗi định dạng không nhận dạng được

Nguyên nhân gốc: Nội dung bộ đệm không phải là định dạng nhị phân có thể nhận dạng được, hoặc bộ đệm bị hỏng (bị cắt ngắn, mã hoá sai, hoặc base64 thay vì byte thô).

Chẩn đoán:

const buffer = fs.readFileSync('model.glb');
console.log('Buffer size:', buffer.length, 'bytes');
console.log('First 4 bytes (hex):', buffer.slice(0, 4).toString('hex'));
// GLB magic: 676c5446 ("glTF")
// STL binary starts with 80 bytes of header; no fixed magic
// OBJ is text: openFromBuffer may not detect format

Sửa: Đối với các định dạng dựa trên văn bản (OBJ, COLLADA), truyền lớp tùy chọn phù hợp để gợi ý định dạng:

import { ObjLoadOptions } from '@aspose/3d/formats/obj';
scene.openFromBuffer(buffer, new ObjLoadOptions());

Tệp GLB đầu ra mở dưới dạng JSON trong các trình xem 3D

Nguyên nhân gốc: GltfSaveOptions.binaryMode mặc định là false, tạo ra .gltf đầu ra JSON ngay cả khi tên tệp đầu ra là .glb.

Sửa: Đặt rõ ràng binaryMode = true:

import { GltfSaveOptions } from '@aspose/3d/formats/gltf';

const opts = new GltfSaveOptions();
opts.binaryMode = true;
scene.save('output.glb', opts);

Kết quả STL không có dữ liệu màu hoặc vật liệu trong slicer

Nguyên nhân gốc: Định dạng STL không hỗ trợ vật liệu hoặc màu trong tiêu chuẩn của nó. Các slicer hỗ trợ màu sử dụng các phần mở rộng độc quyền không được hỗ trợ bởi @aspose/3d.

Sửa: Xuất sang 3MF thay thế, vì nó hỗ trợ siêu dữ liệu màu và vật liệu:

scene.save('output.3mf');

Lỗi biên dịch TypeScript

Property 'controlPoints' does not exist on type 'Entity'

Nguyên nhân gốc: Entity là lớp cơ sở; Mesh là kiểu cụ thể có các thuộc tính hình học. Bạn cần một instanceof bảo vệ trước khi truy cập các thành viên đặc thù của lưới.

Sửa:

import { Mesh } from '@aspose/3d';

if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    console.log(mesh.controlPoints.length);
}

Type 'null' is not assignable to type 'Node'

Nguyên nhân gốc: getChildNode() trả về Node | null. Chế độ nghiêm ngặt của TypeScript yêu cầu bạn xử lý trường hợp null.

Sửa:

const child = node.getChildNode('wheel');
if (!child) throw new Error('Node "wheel" not found');
// child is now Node, not null

Cannot find name 'GltfSaveOptions'

Nguyên nhân gốc: GltfSaveOptions nằm trong mô-đun sub-path @aspose/3d/formats/gltf, không phải gốc của gói.

Sửa: Import từ sub-path:

import { GltfSaveOptions } from '@aspose/3d/formats/gltf';

Vấn đề bộ nhớ và hiệu năng

Quá trình hết bộ nhớ khi xử lý các tệp FBX lớn

Nguyên nhân gốc: Các tệp FBX rất lớn (>200 MB) chiếm lượng heap đáng kể. Heap mặc định của Node.js là khoảng 1.5 GB trên hệ thống 64-bit nhưng có thể không đủ cho các tệp đa cảnh.

Khắc phục: Tăng kích thước heap của Node.js:

node --max-old-space-size=8192 dist/convert.js

Cũng nên xử lý các tệp theo thứ tự thay vì song song khi bộ nhớ bị hạn chế:

for (const file of files) {
    const scene = new Scene();
    scene.open(file);
    scene.save(file.replace('.fbx', '.glb'));
    // scene goes out of scope; GC can reclaim
}

Xem thêm

 Tiếng Việt