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 ملف sidecar.

إصلاح: تعيين 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 حتى عندما يكون اسم ملف الإخراج هو .glb.

إصلاح: تعيين صراحةً binaryMode = true:

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

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

إخرَاج STL لا يحتوي على بيانات اللون أو المادة في أداة القطع

السبب الجذري: لا يدعم تنسيق STL المواد أو اللون في مواصفاته القياسية. تستخدم Color‑capable slicers امتدادات مملوكة غير مدعومة من @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 MB) تستهلك مساحة heap كبيرة. الheap الافتراضي في Node.js هو ~1.5 GB على الأنظمة 64-bit لكن قد لا يكون كافيًا لملفات متعددة المشاهد.

إصلاح: زيادة حجم heap في 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
}

انظر أيضًا

 العربية