Aspose.3D FOSS
TypeScript
Руководства по устранению неполадок

Руководства по устранению неполадок

Эта страница охватывает наиболее распространённые ошибки, возникающие при использовании @aspose/3d в проектах TypeScript и Node.js, с объяснением первопричин и проверенными исправлениями.

Ошибки разрешения модулей

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

Корневая причина: Стратегия разрешения модулей TypeScript не поддерживает экспорт подпутей в стиле Node.js (exports в package.json) если не moduleResolution установлен в node или node16.

Исправить: Установить moduleResolution на "node" в вашем tsconfig.json:

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

Если вы используете TypeScript 5.x с "module": "node16" или "module": "nodenext", используйте "moduleResolution": "node16" для соответствия.

SyntaxError: Cannot use import statement in a module

Коренная причина: Скомпилированный JavaScript запускается с require() семантикой, но вывод содержит ES module import синтаксис; это происходит, когда module установлено в es2020 или esnext но среда выполнения Node.js ожидает CommonJS.

Исправление: Используйте "module": "commonjs" в tsconfig.json и запустите скомпилированные .js файлы с node непосредственно:

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

Затем скомпилируйте и запустите:

npx tsc
node dist/main.js

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

Коренная причина: Пакет не установлен, или node_modules устарел.

Исправить:

npm install @aspose/3d

Проверьте установку:

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

Пустая сцена после загрузки

Сцена загружается, но rootNode.childNodes пустая

Коренная причина (1): Формат файла размещает всю геометрию непосредственно на rootNode.entity вместо дочерних узлов. Это часто встречается в одно-объектных STL‑файлах.

Диагностика:

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}`);

Исправить: Обход, начиная с scene.rootNode : самого себя, а не только его дочерних элементов:

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);

Коренная причина (2): Путь к файлу неверен или файл имеет нулевой размер. Проверьте, что файл существует и не пустой, прежде чем вызывать 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}`);

Список материалов пуст после загрузки OBJ

Коренная причина: Загрузка материалов отключена по умолчанию в ObjLoadOptions. Библиотека загружает геометрию без чтения .mtl вспомогательного файла.

Исправить: Установить 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);

Также убедитесь, что .mtl файл находится в той же директории, что и .obj файл, так как библиотека разрешает его относительно .obj пути.

Ошибки формата и ввода/вывода

openFromBuffer выдаёт ошибку «неизвестный формат»

Коренная причина: Содержимое буфера не является распознаваемым бинарным форматом, либо буфер повреждён (обрезан, неверная кодировка или base64 вместо необработанных байтов).

Диагностика:

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

Исправление: Для текстовых форматов (OBJ, COLLADA) передайте соответствующий класс параметров, чтобы указать формат:

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

Полученный GLB открывается как JSON в 3D‑просмотрщиках

Коренная причина: GltfSaveOptions.binaryMode по умолчанию false, создавая .gltf JSON‑вывод даже когда имя выходного файла is .glb.

Исправить: Явно установить binaryMode = true:

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

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

В выводе STL нет данных о цвете или материале в слайсере

Коренная причина: Формат STL не поддерживает материалы или цвет в своей стандартной спецификации. Слайсеры, поддерживающие цвет, используют проприетарные расширения, которые не поддерживаются @aspose/3d.

Исправить: Экспортируйте в 3MF вместо этого, который поддерживает цвет и метаданные материалов:

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

Ошибки компиляции TypeScript

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

Коренная причина: Entity является базовым классом; Mesh является конкретным типом с геометрическими свойствами. Вам нужен instanceof проверка перед доступом к членам, специфичным для сетки.

Исправить:

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'

Коренная причина: getChildNode() возвращает Node | null. Режим строгой типизации TypeScript требует обработки случая null.

Исправить:

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

Cannot find name 'GltfSaveOptions'

Коренная причина: GltfSaveOptions находится в подпути модуля @aspose/3d/formats/gltf, а не в корне пакета.

Исправление: Импорт из подпути:

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

Проблемы с памятью и производительностью

Процесс исчерпывает память при работе с большими файлами FBX

Коренная причина: Очень большие файлы FBX (>200 МБ) занимают значительный объём кучи. По умолчанию Node.js выделяет ~1,5 ГБ кучи на 64‑разрядных системах, но этого может быть недостаточно для файлов с несколькими сценами.

Исправление: Увеличьте размер кучи Node.js:

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

Также обрабатывайте файлы последовательно, а не параллельно, когда память ограничена:

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
}

См. также

 Русский