# @ar-js-org/ar\.js 中文文档

规范地址：https://npmcn.com/package/%40ar-js-org/ar.js/

版本：3\.4\.8
npm 元数据更新时间：2026-03-16T12:14:32.612Z
中文译文更新时间：2026-11-06T13:20:44.568Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ar-js-org/ar.js
原文对照：https://npmcn.com/package/%40ar-js-org/ar.js/?lang=original
项目主页：https://github.com/AR-js-org/AR.js/
源码仓库：https://github.com/AR-js-org/AR.js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：16.6 MB，24 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：3 个
- 首次发布：2021-11-05T11:34:14.159Z
- 最新版本发布：2026-03-16T12:14:32.463Z
- 近 30 天下载量：3250（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 1 个）

## 中文简介

有效增强网络现实

## 安装

```sh
npm install @ar-js-org/ar.js
```

也可以使用：`pnpm add @ar-js-org/ar.js`、`yarn add @ar-js-org/ar.js`、`bun add @ar-js-org/ar.js`

## README

# AR.js - 网上增强现实

[![CI](https://github.com/AR-js-org/AR.js/actions/workflows/CI.yml/badge.svg)](https://github.com/AR-js-org/AR.js/actions/workflows/CI.yml) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier) [![Gitter chat](https://badges.gitter.im/AR-js/Lobby.png)](https://gitter.im/AR-js/Lobby) [![Twitter Follow](https://img.shields.io/twitter/follow/nicolocarp.svg?style=plastic&label=nicolocarpignoli-%F0%9D%95%8F\(Twitter\)&style=plastic)](https://twitter.com/nicolocarp) [![Twitter Follow](https://img.shields.io/twitter/follow/jerome_etienne.svg?style=plastic&label=jeromeetienne-%F0%9D%95%8F\(Twitter\)&style=plastic)](https://twitter.com/jerome_etienne)

你现在可以拥有AR.js的第一个承诺了[开口海](https://opensea.io/assets/matic/0xe7ea2e2be12c257d376400cb231d8ee51e972bd6/3962549295964122998537137060348053157629730105441540397501924171148500367064/)

AR.js是网络上Admented Reality的轻量级库,包含图像跟踪,基于位置的AR和Marker跟踪等功能.

_**30/12/21 最新情况:** 现在还有一个全新的OSS Web AR JS图书馆,叫做: [明达](https://github.com/hiukim/mind-ar-js)。 。 。 . 如果你需要一个伟大的图像跟踪功能(同时也是多个图像跟踪)和Face跟踪, [去看一看,你看看,好吗](https://github.com/hiukim/mind-ar-js)来啊!  
目前,AR.js仍然是提供基于Marker和基于位置的AR特性的唯一库._

这个项目是由 [@jeromeetienne (法语)](https://github.com/jeromeetienne)由Nicolò Carpignoli管理,现由AR.js org维护.

AR.js的频繁更新您可以跟踪 [@ 官方 X (twitter) 账户](https://twitter.com/ARjs_Library) 看着这回波!

Logo是礼貌的 [西蒙·普尔特](https://twitter.com/viralinfo) 。 。 。 .

* * *

### 现在有官方文件了

### 检查一下: [AR.js 正式文件](https://ar-js-org.github.io/AR.js-Docs/)。 。 。 .

如果你想先看AR.js的潜力,你可以继续这个Readme.

* * *

AR. js要来不同的建筑。 两者都得到维护。 他们是独家的.

请导入您需要的项目, 而不是同时导入 :

-   **AR.js 有图像跟踪+基于位置的AR(AFRAME):**
    
    -   [https://raw.githack.com/AR-js-org/AR.js/master/aframe/building/aframe-ar-nft.js 互联网档案馆的存檔,存档日期2013-12-21](https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar-nft.js)
-   **AR.js 有标记跟踪+基于位置的AR(AFRAME):**
    
    -   [页:1](https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar.js)
-   **AR.js 有图像跟踪+标记跟踪(Treejs):**
    
    -   [https://raw.githack.com/AR-js-org/AR.js/master/ three.js/building/ar-tex.js (中文(简体) )](https://raw.githack.com/AR-js-org/AR.js/master/three.js/build/ar-threex.js)
    
    如果您需要 ARjs 命名空间导入 ar.js:
    
    -   [https://raw.githack.com/AR-js-org/AR.js/master/ three.js/building/ar.js 互联网档案馆的存檔,存档日期2013-12-11](https://raw.githack.com/AR-js-org/AR.js/master/three.js/build/ar.js)
-   **AR.js 具有基于地点的AR(Treejs):**
    
    -   [https://raw.githack.com/AR-js-org/AR.js/master/ three.js/building/ar-tex-location- only.js 互联网档案馆的存檔,存档日期2013-12-12](https://raw.githack.com/AR-js-org/AR.js/master/three.js/build/ar-threex-location-only.js)

您也可以导入特定版本替换 `master` 带有版本标签的关键字 :

```html
  <script src="https://raw.githack.com/AR-js-org/AR.js/3.4.8/aframe/build/aframe-ar-nft.js">
```

## 开始吧

### 🖼 **图像跟踪**

请遵循这些简单的步骤:

-   创建一个新的工程,其代码如下( 或) [打开此活实例](https://ar-js-org.github.io/.github/profile/aframe/examples/image-tracking/nft/) 并直接进入最后一步)
-   在服务器上运行
-   打开您的手机网站
-   扫描 [此图片](https://raw.githubusercontent.com/AR-js-org/AR.js/master/aframe/examples/image-tracking/nft/trex-image-big.jpeg) 通过相机看到内容.

```html
<script src="https://cdn.jsdelivr.net/gh/aframevr/aframe@1.6.0/dist/aframe-master.min.js"></script>
<script src="https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar-nft.js"></script>

<style>
  .arjs-loader {
    height: 100%;
    width: 100%;
    position: absolute;
    top: 0;
    left: 0;
    background-color: rgba(0, 0, 0, 0.8);
    z-index: 9999;
    display: flex;
    justify-content: center;
    align-items: center;
  }

  .arjs-loader div {
    text-align: center;
    font-size: 1.25em;
    color: white;
  }
</style>

<body style="margin : 0px; overflow: hidden;">
  <!-- minimal loader shown until image descriptors are loaded -->
  <div class="arjs-loader">
    <div>Loading, please wait...</div>
  </div>
  <a-scene
    vr-mode-ui="enabled: false;"
    renderer="logarithmicDepthBuffer: true; precision: medium;"
    embedded
    arjs="trackingMethod: best; sourceType: webcam;debugUIEnabled: false;"
  >
    <!-- we use cors proxy to avoid cross-origin problems ATTENTION! you need to set up your server -->
    <a-nft
      type="nft"
      url="your-server/https://raw.githack.com/AR-js-org/AR.js/master/aframe/examples/image-tracking/nft/trex/trex-image/trex"
      smooth="true"
      smoothCount="10"
      smoothTolerance=".01"
      smoothThreshold="5"
    >
      <a-entity
        gltf-model="your-server/https://raw.githack.com/AR-js-org/AR.js/master/aframe/examples/image-tracking/nft/trex/scene.gltf"
        scale="5 5 5"
        position="150 300 -100"
      >
      </a-entity>
    </a-nft>
    <a-entity camera></a-entity>
  </a-scene>
</body>
```

### 基于位置的示例

请遵循这些简单的步骤:

-   创建新工程, 并修改以下片段 `add-your-latitude` 财务报告和审定财务报表 `add-your-longitude` 与你的纬度和经度,没有 `<>`。 。 。 .
-   在服务器上运行
-   激活您的手机上的 GPS 并导航到示例 URL
-   看看周围 你应该看到文字看着你, 出现在要求的位置上, 即使你环顾四周移动.

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <title>GeoAR.js demo</title>
    <script src="https://aframe.io/releases/1.6.0/aframe.min.js"></script>
    <script src="https://unpkg.com/aframe-look-at-component@1.0.0/dist/aframe-look-at-component.min.js"></script>
    <script src="https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar-nft.js"></script>
  </head>

  <body>
    <a-scene
      vr-mode-ui="enabled: false"
      arjs="sourceType: webcam; videoTexture: true; debugUIEnabled: false;"
    >
      <a-text
        value="This content will always face you."
        look-at="[gps-camera]"
        scale="120 120 120"
        gps-entity-place="latitude: <add-your-latitude>; longitude: <add-your-longitude>;"
      ></a-text>
      <a-camera gps-camera rotation-reader> </a-camera>
    </a-scene>
  </body>
</html>
```

### 基于标记的示例

请遵循这个简单的步骤:

-   创建一个新的工程,其代码如下( 或) [打开此活实例](https://ar-js-org.github.io/.github/profile/aframe/examples/marker-based/basic.html) 并直接进入最后一步)
-   在服务器上运行
-   打开您的手机网站
-   扫描 [此图片](https://raw.githubusercontent.com/AR-js-org/AR.js/master/data/images/hiro.png) 通过相机看到内容.

```html
<!DOCTYPE html>
<html>
    <script src="https://aframe.io/releases/1.6.0/aframe.min.js"></script>
    <!-- we import arjs version without NFT but with marker + location based support -->
    <script src="https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar.js"></script>
    <body style="margin : 0px; overflow: hidden;">
        <a-scene embedded arjs>
        <a-marker preset="hiro">
            <!-- we use cors proxy to avoid cross-origin problems ATTENTION! you need to set up your server -->
            <a-entity
            position="0 0 0"
            scale="0.05 0.05 0.05"
            gltf-model="your-server/https://raw.githack.com/AR-js-org/AR.js/master/aframe/examples/image-tracking/nft/trex/scene.gltf"
            ></a-entity>
        </a-marker>
        <a-entity camera></a-entity>
        </a-scene>
    </body>
</html>
```

重要的东西! 请注意,如果您指的是外部资源,在任何应用程序中,特别是那些使用NFT的应用程序中,如果这些资源不在代码的同一服务器中,您将会遇到CORS问题. 如果您无法看到跟踪, 请打开浏览器 Dev 工具, 并检查控制台是否有 CORS 错误 。 如果是的话,你必须纠正这些错误才能看到自己的内容. 正确的修补是将您的资源放置在代码的同一服务器上.

如果您无法做到这一点, 您可以在任何服务器中设置代理服务器以解决这个问题( Name[https://github.com/Rob--W/cors-任何地方](https://github.com/Rob--W/cors-anywhere)) (中文(简体) ). 请注意,一些托管服务的政策不允许使用这种服务器。 在使用托管服务政策以避免账户暂停前, 总是检查托管服务政策

学习更多关于 [AR.js 正式文件](https://ar-js-org.github.io/AR.js-Docs/)。 。 。 .

## ES6 npm 软件包

您可以安装 **经常预算.js** 与 **无** ,并在任何支持 npm 模块的相容项目(React.js, Vue.js, Next.js 或 whatelse)中使用来安装它运行:

```
// Install with npm
npm install @ar-js-org/ar.js
```

```
// Install with yarn
yarn add @ar-js-org/ar.js
```

将一些例子改为: [问题](https://github.com/AR-js-org/AR.js/issues/234)。 。 。 .

### 新建导入语法 `ar-threex.mjs` 财务报告和审定财务报表 `ar.mjs`

在更新3.4.6之后, `three.js` 现在可以使用ES模块语法导入. 为了与本标准保持一致, `ar-threex.mjs`, (中文(简体) ),`ar.mjs` 财务报告和审定财务报表 `ar-threex-location-only.mjs` 还应使用导入地图同样的方式导入。 以下是如何在您的项目中导入这些模块的例子 :

```html
// Example importing ar-threex.mjs
<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.164.0/build/three.module.js",
    "threex": "./path/to/ar-threex.mjs",
  }
}
</script>

<script type="module">
import * as THREE from 'three';
import { ArToolkitSource, ArToolkitContext, ArMarkerControls }  from 'threex'

// Your AR.js code here
</script>
```

读取此寄存器中包含的示例以获取更多信息,但基本上唯一的更改是导入语法.

## 解决问题、专题请求、社区

**你可以在旧的上找到很多帮助 [AR.js储存库问题](https://github.com/jeromeetienne/AR.js/issues)。请搜索公开/非公开的问题,您可能会发现有趣的东西.**

### 捐款

从打开错误报告到创建牵引请求: 每一份贡献都是 感谢和欢迎。 如果你打算执行一个新的功能或改变 请先创建一个问题 。 这样我们就能确保你的宝贝 工作不是徒劳的.

### 问题

如果您有配置或设置问题, 请张贴 问题 [叠叠流](https://stackoverflow.com/search?q=ar.js)。 。 。 . 你也可以在我们的 [吉特聊天室](https://gitter.im/AR-js/Lobby)

**如果您发现了一个错误或者有特性建议,请随意在Github上创建一个问题.**

### 提交更改

得到一些反馈后,推入你的叉子并提交拉力请求. 我们 可能建议一些修改或改进或替代办法,但小的修改 您的拉动请求应该被迅速接受.

有些事情会增加你的拉力请求被接受的机会:

-   遵循现有的编码样式
-   写一个 [好承诺消息](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)

## 许可证

没错 **全部开源**artoolkit5 -js是 LGPLv3 许可证和额外许可. 我所有的代码在AR

法律细节请检查 [artoolkit5-js许可证](https://github.com/AR-js-org/artoolkit5-js/blob/master/LICENSE) 财务报告和审定财务报表 [AR.js许可证](https://github.com/AR-js-org/AR.js/blob/master/LICENSE)。 。 。 .

完整更改日志 : [AR.js 更改日志](https://github.com/AR-js-org/AR.js/blob/master/CHANGELOG.md)

## 常见问题

### @ar-js-org/ar\.js 是什么？

有效增强网络现实

### 如何安装 @ar-js-org/ar\.js？

在项目目录运行 npm install @ar-js-org/ar\.js，或使用 pnpm add / yarn add / bun add。

### @ar-js-org/ar\.js 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/ar-js-org\_\_ar\.js 是否存在。

### @ar-js-org/ar\.js 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @ar-js-org/ar\.js 可以商用吗？

@ar-js-org/ar\.js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ar-js-org/ar\.js 的下载量有多少？

根据 npm 官方下载统计，@ar-js-org/ar\.js 在 2026/10/07 – 2026/11/05 这 30 天内被下载 3,250 次，日均约 108 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ar-js-org/ar\.js 还在维护吗？

最新版本 3\.4\.8 发布于 2026/03/16（7 个月前）；至今共发布 18 个版本，其中过去 12 个月发布了 1 个；首次发布于 2021/11/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。