如何在Ionic Vue项目中正确集成实现AR.js功能

不要在Ionic Vue项目中使用iframe加载AR.js页面，会存在不可控的权限和上下文冲突问题

iframe方案失效核心原因 #

• AR.js需要调用当前页面上下文的摄像头、WebGL等敏感API，iframe的沙箱隔离机制会直接阻断这类权限申请
• Ionic Webview的默认安全策略禁止iframe跨域访问硬件接口，即使配置同源也容易出现上下文冲突导致AR功能无法初始化

实现步骤 #

步骤1：引入核心依赖 #

提前将AFRAME、AR.js的生产版本JS文件下载到项目public/assets目录下，避免外链加载的跨域问题，随后在项目根目录的public/index.html的head标签内引入本地依赖：

<script src="%PUBLIC_URL%/assets/aframe.min.js"></script>
<script src="%PUBLIC_URL%/assets/aframe-ar.js"></script>

步骤2：配置Vue自定义元素忽略规则 #

AR.js基于AFRAME实现，会用到大量a-开头的自定义标签，需要配置Vue跳过解析这类元素，避免模板编译报错：
如果是Vite构建的项目，修改vite.config.ts：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // 忽略所有a-开头的自定义元素
          isCustomElement: tag => tag.startsWith('a-')
        }
      }
    })
  ]
})

如果是Vue CLI构建的项目，修改vue.config.js：

module.exports = {
  chainWebpack: config => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => {
        options.compilerOptions = {
          isCustomElement: tag => tag.startsWith('a-')
        }
        return options
      })
  }
}

步骤3：配置应用摄像头权限 #

如果使用Capacitor打包移动端应用，需要在capacitor.config.ts中声明摄像头权限：

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: '你的应用包名',
  appName: '你的应用名称',
  webDir: 'dist',
  server: {
    androidScheme: 'https' // AR功能要求运行在https环境，本地调试用localhost也可正常运行
  },
  android: {
    permissions: ['android.permission.CAMERA']
  },
  ios: {
    permissions: {
      NSCameraUsageDescription: "需要使用摄像头完成AR识别功能"
    }
  }
};

export default config;

步骤4：编写AR页面组件 #

直接在Home.vue的ion-content区域编写AR场景代码即可，不需要嵌套iframe：

<template>
  <ion-page>
    <ion-header>
      <ion-toolbar>
        <ion-title>AR演示</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content fullscreen>
      <div class="ar-wrapper">
        <a-scene 
          arjs="sourceType: webcam; detectionMode: mono_and_matrix; matrixCodeType: 3x3;"
          vr-mode-ui="enabled: false"
        >
          <!-- 示例用Hiro识别Marker，可替换为自定义Marker -->
          <a-marker preset="hiro">
            <!-- 识别到Marker后显示的3D元素，此处为示例立方体 -->
            <a-box position="0 0.5 0" rotation="45 45 0" color="#4CC3D9"></a-box>
          </a-marker>
          <a-entity camera></a-entity>
        </a-scene>
      </div>
    </ion-content>
  </ion-page>
</template>

<script setup lang="ts">
import { IonPage, IonHeader, IonToolbar, IonTitle, IonContent } from '@ionic/vue';
</script>

<style scoped>
.ar-wrapper {
  width: 100%;
  height: 100%;
  position: relative;
  overflow: hidden;
}
/* 覆盖AR场景默认定位，避免溢出Ion内容区域 */
a-scene {
  position: absolute !important;
  top: 0;
  left: 0;
  width: 100% !important;
  height: 100% !important;
}
</style>

调试注意事项 #

• 本地调试必须使用localhost或者https协议，否则浏览器会禁止摄像头权限调用
• 移动端打包后首次启动会触发摄像头权限申请，用户同意后才能正常使用AR功能
• 自定义Marker可通过AR.js官方工具生成对应配置，替换a-marker标签的preset属性即可

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