AR.JS自定义Marker无法正常工作，求正确实现方法及代码排查

Hey there! Let's figure out why your custom AR.js marker isn't working and get it up and running properly. Let's start with the most obvious issues in your code, then move to other common pitfalls.

First: Fix Your Marker Tag Syntax #

Your current marker code has a conflict between preset="custom" and type="pattern". The preset attribute is only for using AR.js's built-in markers like hiro or kanji—when you're using a custom pattern marker, you don't need the preset attribute at all. This conflict is likely confusing the AR.js library.

Here's the corrected marker code:

<a-marker type="pattern" url="img/pattern-marker.patt">
  <a-box position='0 0.5 0' material='color: black;' soundhandler></a-box>
</a-marker>

Next: Check Your .patt File & Source Image #

Your choice of a simple black-and-white circle is probably causing tracking issues. AR.js relies on unique, asymmetric visual features to track markers—circles are perfectly symmetric, so the library can't distinguish its orientation or lock onto it reliably.

To fix this:

• Use a more distinct, asymmetric image (e.g., a square with an off-center symbol, or text with unique lettering)
• Generate your .patt file using AR.js's official pattern generator (make sure your source image is around 200x200 pixels, high contrast, and has clear, unique details)
• Double-check that the .patt file was generated successfully—if the tool threw an error, your image might be too simple or low-quality.

Verify File Path & Loading #

Open your browser's developer tools (F12 → Network tab) and refresh your page. Look for pattern-marker.patt in the list of loaded files:

• If you see a 404 error, your path is wrong. Make sure the img folder is in the same directory as your HTML file, or adjust the url to match your file structure (e.g., ./img/pattern-marker.patt for relative paths, or an absolute path for testing)
• If the file loads with a 200 status, move on to the next check.

Ensure Your Scene Structure Is Complete #

AR.js requires a specific scene setup to work. Make sure your marker is wrapped inside an <a-scene> with the arjs attribute, and that you have a camera entity:

<a-scene arjs>
  <!-- Your corrected marker goes here -->
  <a-marker type="pattern" url="img/pattern-marker.patt">
    <a-box position='0 0.5 0' material='color: black;' soundhandler></a-box>
  </a-marker>
  <!-- Don't forget the camera! -->
  <a-entity camera></a-entity>
</a-scene>

Without the arjs attribute on the scene, AR tracking won't initialize, and missing the camera will break the view entirely.

Check Your Test Environment #

• HTTPS Requirement: Browsers require HTTPS (except for localhost) to access the camera. If you're testing on a remote server, make sure it's using HTTPS. If you're working locally, localhost is fine.
• Camera Permissions: When you load the page, make sure you grant camera access to your browser. If you blocked it accidentally, go to your browser settings to reset permissions.

Print & Physical Marker Tips #

If you're testing with a printed marker:

• Don't stretch or skew the image when printing—keep its original aspect ratio
• Print it at a reasonable size (not too small, not too large; 10-15cm square works well)
• Make sure the print is clear, with no smudges or faded areas

内容的提问来源于stack exchange，提问作者Peter Lum