aframe

aframevrMIT活跃维护

用 HTML 声明式语法快速搭建 WebVR/AR 场景，无需深入 WebGL 细节，就能在浏览器里做出可跨头显运行的虚拟现实体验。

:a: Web framework for building virtual reality experiences.

v1.8.0发布于 2026-06-24 12:03 UTC17,693star +1 / 7 天4,409fork同步于 2026-11-10 05:23 UTC

WebVR 虚拟现实声明式3D 实体组件系统浏览器渲染

对比 GitHub 官网 3d aframe augmented-reality daydream ecs

怎么上手

从 README 代码块原样提取，可能是其中一种安装方式

原文

npm install --save aframe
git clone https://github.com/aframevr/aframe.git  # Clone the repository.
npm start  # Start the local development server.
npm run start:https

硬件要求

README 没有说明硬件要求。

下载：源码 zip·GitHub Releases（安装包）本站不镜像安装包

项目说明

这个项目的说明还在生成中，先参考下面「最近发版」和 README。

最近发版

5 个版本v1.8.0

全部 release

v1.8.0最新正式版2026-06-24 · 2026-06-24 12:03 UTC
1.8.0 (June 23, 2026)

Major Changes
- Bug fixes and improvements.
- Update THREE to r184
Bug fixes
- Fix issue when a loaded cube texture doesn't contribute to light probes (fix #5734) (#5735) (@mrxz)
- Fix issue when url of gltf-model changes when model is still loading (#5739) (@mrxz)
- Address unsafe-eval error with with strict Content Security Policy (CSP) (fix #5028) (#5821) (@vincentfretin, @samiemad, @mrxz)
- Replace Clock instance by Timer instance. Clock is deprecated in THREE r183+ (#5800) (@vincentfretin)
- Remove pcfsoft shadow type in shadow component, deprecated in THREE r182+ fallback to pcf (#5798) (@vincentfretin, @mrxz)
- Set dialogs text color explictitly to ovverride browser defaults that might result on white text on white background (#5814) (@vincentfretin)
- Fix issue when a tracked controller disconnects and reconnects (#5804) (@vincentfretin)
- Fix hand-controls orientation on Meta Quest Controllers (fix #5570, #5305, #5321) (#5766) (@filandra)
- Fix missing pixel row when capturing an image with the screenshot component (fix #5789) (#5790) (@diarmidmackenzie)
- Fix issue with loading screen dismissed prematurely while images are still loading (#5779) (@vincentfretin)
- Click event triggered on the wrong controller with the cursor component (#5782) (@vincentfretin)
- Fix incorrect error handling when an image fails to load in the material component (#5781) (@vincentfretin, @mrxz)
- Prevent erronously caching images that have failed to load (#5778)
- Identify controllers by id instead of idPrefix in tracked-controls (fix #5772) (#5774) (@vincentfretin)
- Fix issue where controller model is not visibile when toggling between hands and controllers (fix #5757) (#5777) (@vincentfretin)
- Use unique cache keys per file type when caching to match THREE r178+ convention (#5776) (@vincentfretin)
- Fix axis names for Windows motion controls (#5732) (@hazho)
- Make quad layers feature optional so it works on devices not supporting WebXR layers like Apple Vision Pro (#5722) (@vincentfretin)
- Fix wrong geometry size in layer component (#5723) (@vincentfretin)
- Fix check for XRWebGLBinding existance in layer component (#5721) (@vincentfretin, @mrxz)
- Replace npot property in material component with the more explicit minFilter and magFilter (#5717) (@mrxz)
- Verify this.quadPanelEl exists before toggling the layer visibility (#5708) (@vincentfretin)
Enhancements
- Reintroduce needsRedraw flag to force updates on the layer component (#5724) (@vincentfretin)
- Replace rStats with stats-gl in stats component (fix #5397) (#5700) (@arvind-iyer)
- Remove stats div from DOM when removing the stats component (#5733) (@vincentfretin)
- Update shadow light properties only for lights that support shadows (#5748) (@mrxz)
- Improve Logitech MX support: Enable use in AR mode, support variable brush stroke on button / tip pressuer (#5756) (@FilipeLopesPires)
- Remove obsolete variable assignments in tracked-controls component (#5770) (@vincentfretin)
- Remove obsolete / dead logic to rotate the Meta Touch model thumbstick (#5775) (@vincentfretin)
- Set raycaster.camera to the active camera in order to raycast against sprites (@vincentfretin)
- Expose premultipliedAlpha on material component (#5810) (@vincentfretin)
- Docs improvements (@vincentfretin, @thatguyjk, @Utopiah, @ccoenen, @mrxz, @vaibhavyxx, @Omegahed, @dmarcos)
- Improve tests (@vincentfretin, @kitsiosk, @dmarcos)
- Build system improvements (@vincentfretin, @mrxz, @daj, @dmarcos)
- Set generateMipmaps for material component (#5726) (@vincentfretin, @mrxz)
- Don't unnecessarily initialize 6 canvas for quad layers. (#5707) (@vincentfretin)
- Set meshMixin property default value to correct type in real-world-mesh componet (#5712) (@vaibhavyxx)
- Use XRMediaBinding.createQuadLayer to render flat video on a layer (@vincentfretin)
Deprecations
- If you us
v1.7.12025-04-01 · 2025-04-01 06:58 UTC
查看更新说明
1.7.1 (Apr 1, 2025)

Bug fixes
- Add package-lock.json for consistency when generating builds (#5693) (@vincentfretin)
- hand-tracking-controls components emits controllermodelready for consistency with other input controls components (#5685) (@coderofsalvation)
- Fix inspector when post-processing is enabled (#5684) (@vincentfretin)
- Fix Next.js skipping A-Frame CSS styles (#5682) (@vincentfretin)
- Fix ar-hit-test component. Initialize on enter-vr event instead of sessionstart (#5680) (@vincentfretin)
- Docs and examples improvements (@jgbarah, @vincentfretin, @diarmidmackenzie, @dmarcos)
v1.7.02025-02-20 · 2025-02-20 23:07 UTC
查看更新说明
1.7.0 (Feb 20, 2025)

Post-processing, ES modules and importmap, WebGPU and TSL support, Logitech MX Ink integration and more.

Major Changes
- Update to THREE r173 (@dmarcos)
- Import maps support and replacement of CommonJS with ES Modules (@mrxz, @vincentfretin)
- Experimental post-processing support. It works both in regular and immersive modes (@enzofrancescaHM, @mrxz, @vincentfretin, @CodyJasonBennett)
- Support for Logitech MX Ink tracked pen (@dmarcos)
- Initial WebGPU support (@vincentfretin)
Bug fixes
- Remove unused width and height properties from flat and standard shaders (#5647) (@mrxz)
- Relax the clientWidth constraint in the controls tests. Fix tests on Ubuntu (#5641) (@vincentfretin)
- Check if XRSession exists before attaching inputsourcechange listener (#5631) (@mrxz)
- Don't apply anchor scale (only position and rotation) to an anchored entity (#5633) (@mrxz)
- Wait until referenceSpace is available befor initializing compositor layers (#5626) (@vincentfretin)
- Remove raycaster-closest-entity-changed listener when removing the cursor component (#5625) (@vincentfretin)
- Handle cursor rayOrigin updates and rayOrigin: mouse when component attached to an entity and not a-scene (fix #4759) (#4760) (@kylebakerio)
- Fix light shadow frustum visualization via CameraHelper (fix #5098) (#5099) (@IanSweeneyAC, @dmarcos)
- Prevent loading cubemap for a probe light when envMap is not set (fix #5610) (#5611) (@mrxz)
- Prevent redundant pinchstarted events on a hand tracking pinch gesture (#5609) (@mrxz)
- Improve cursor component xrselect logic. Handle rayOrigin property changes and account for camera rigs when calculating the raycaster direction (#5606) (@mrxz, @vincentfretin)
- Fix Apple Vision Pro detection logic to prevent false positives on iPad and iPhone (fix #5605) (#5607) (@vincentfretin)
- Remove fullscreen CSS styles from the document element when a-scene is disconnected (#5602) (@gunhaxxor)
- Adjust light intensity defaults and examples to account for WebGLRenderer.useLegacyLights deprecation in THREE r165 (#8813d3d2) (@dmarcos)
- Fix model visibility logic of tracked hands and controllers when there are input switches (e.g hands to controllers) (#fa0cc748) (@dmarcos)
- Prevent a-loader-title div (A-Frame created HTML element) to be serialized (#5574) (@vincentfretin)
- Disable magic window mode in Vision Pro that is only suitable for handheld mobile devices (#5560) (@dmarcos)
- Don't bubble <a-asset-item> error event that was preventing some tests to execute (#5548) (@mrxz)
- Don't stringify properties with undefined values to prevent flushToDOM to produce properties with the undefined string (#5549) (@mrxz)
- Fix serialization / stringification of asset type properties. When an HTML element they got exported incorrectly as e.g [object HTMLImageElement] (#5544) (@mrxz, @vincentfretin)
- Refresh raycasted objects only when the objects raycaster component property changes. Prevent unnecessary costly updates (#5542) (@vincentfretin)
- Fix issue when using <a-cubemap> as texture component envMap (@Omegahed, @mrxz)
- Fix incorrect texture reference counting, potentially leading to exceptions upon disposal of the texture (#5529) (@mrxz)
- Eliminate incorrect "unknown property" warnings from dynamic schema components (#5526) (@mrxz)
Enhancements
- Bump to THREE to r173 (@dmarcos)
- Post-processing experimental support (#5648) (@enzofrancescaHM, @CodyJasonBennett, @mrxz, @cabanier, @vincentfretin, @dmarcos)
- ES Modules and importmap support (#5632, #5640) (@mrxz, @vincentfretin)
- Support for WebGPURenderer and TSL (#5655) (@vincentfretin)
- Logitech MX Ink integration (@dma
v1.6.02024-05-23 · 2024-05-23 10:35 UTC
查看更新说明
1.6.0 (May 23, 2024)

Tons of bug fixes. Memory management and performance improvements. API to control tick / tock execution order.

Bug fixes
- Update wrist object position and rotation only when joint poses are available (#5438) (@mrxz)
- Fix issue when checking schema properties when a schema changes (#5426) (@mrxz)
- Set correct default value for scene.background when the background component is removed (#5417) (@mrxz)
- Fix fog removal from scene (#5418) (@mrxz)
- Fix Chrome non-passive violation warnings for touchmove and touchstart event handlers (#5511) (@mrxz, @mitchallen)
- Fix bug when loading models on child entities of controllers (#5415) (@mrxz)
- Fix bug in handling processSound callback when sound hadn't loaded yet (#5414) (@mrxz)
- Fix misspelled variable names after using a spell checker (#5462) (@mrxz)
- Fix problem when a shader that declares itself as glsl3 has its version ignored (bbe74f52) (@dmarcos)
- Fix problem when checking for duplicate names of property types (#5475) (@mrxz)
- Fix problem when adding children entities to a hand-tracking-controls entity before the hand model has loaded (12d550c6) (@dmarcos)
- Hide hand-tracking-controls entity when there's no hand tracking available (dbdb9dac) (@dmarcos)
- Fix issues when applying mixins to primitives (#5483) (@mrxz)
- Fix issue when a component is not removed from the DOM via mixin removal / update (#5492) (@mrxz)
- Fix timing issue when initializing XR Layers (#5489) (@zjm-meta)
- Fix problem where scene doesn't wait / timeout on a-asset-items (#5491) (@mrxz)
- Fix bug when using setAttribute on a-scene if a system has not yet initialized (#5482) (@mrxz)
- Fix broken parser cache of getComponentPropertyPath (#5467) (@mrxz)
- Fix issue when shadowMaps are always enabled. Make sure it's only enabled when there's a shadow component present (#5399) (@mrxz)
- Fix issue when children of an entity with hand-tracking-controls don't follow the hand (874fced2) (@dmarcos)
- Fix ES modules support on node (#5522) (@vincentfretin)
- Make rotation axis order is consistent when using setAttribute and modifying object3D directly (#5513) (@mrxz)
- Fix issue when calculating the size of the bounding box of an obb-collider (5da7166e) (@dmarcos)
- Fix issue when the el.hasLoaded flag can be true but not all components have initialized (924dc00e) (@dmarcos)
- Fix issue when trying to remove a mesh before model was loaded in obj-model component (#5499) (@Elettrotecnica)
- Use renderer.useLegacyLights instead of the deprecated renderer.physicallyCorrectLights in THREE (#5389) (@vincentfretin)
- Set correct default value for glslVersion for non-raw shaders (#5388) (@mrxz)
- Remove "skinning: true" option when instanciating a THREE.MeshStandardMaterial object. Property deprecated in THREE (#5386) (@avdynut)
- Fix issue when tracking an unexisting AR Hitest anchor (@hi-liang, @dmarcos) (bcc4bc2cae2b3) (fix #5314)
- Fix issue when layers are not initialized in AR mode (bb1e7a4e) (@dmarcos)
- Fix issue when removing unexisting light probe after exiting vr mode (#5429) (fix #5384) (@Elettrotecnica)
- Fix issue when removing an obb-collider (957237d) (fix #5385)
- Fix typo when requesting layers on the WebXR requiredFeatures list (f7e56a8f) (@dmarcos)
- Fix issue when trying to animate a non existing button on the controller (da8dc146) (@dmarcos)
Performance
- Improve unit tests execution time (#5477) (@mrxz)
- Recycle nextData and previousOldData objects when a component is destroyed preventing memory leaks (#5458) (@mrxz)
- Improve pooling and recycling of internal component objects. Better memory management (#5459) (@mrxz)
- Reduce memory allocations on component update logic (#5474) (@mrxz)
- Improve throttleLeadingAndTrailing implementation to prevent unnecessary allocations (#5476) (@mrxz)
Enhancements
- Introduce before/after component API to control tick / tock exe
v1.5.02023-11-14 · 2023-11-14 18:38 UTC
查看更新说明
Multiview extension, Spatial computing UIs, Mixed Reality features, Quest 3 support and much more!

Check out the new examples: Anchors, World Meshing and Hand Grab Controls

If you find A-Frame valuable consider sponsoring on github. A-Frame is 100% maintained by volunteers and any help is super appreciated.

Bug fixes
- Use renderer.useLegacyLights instead of the deprecated renderer.physicallyCorrectLights in three r150, but keep the physicallyCorrectLights property name for the renderer system for backward compatibility (fix #5293)
- Fix hand-controls animations (#5300)
- Fix outdated link in error message (#5313) (fix #5275) (@kolson25)
- Fix visibility of controller in model-viewer example (#5317) (@DougReeder)
- Fix typo in phong shader properties (#5334) (@nightgryphon)
- Adapt shaders to new THREE API (#5328) (@nightgryphon)
- Traverse meshes instead of using a hardcoded index (#5340) (@diarmidmackenzie)
- Fix examples miscellaneous errors (#5343) (@mrxz)
- Fix back plane resizing when text component changes (#5357) (fix #2764) (@brycethomas)
- Fix switching back and forth from hands to controller input (fix #5373) (@floe, @dmarcos)
Enhancements
- Add hand-tracking-grab-controls component to make any entity manipulable with hands (@dmarcos)
- Add support for WebXR Mesh and Planes Module (real-world-meshing component) (@dmarcos)
- Add support for WebXR Anchors Module (anchored component) (@dmarcos)
- Add support OVR_multiview extension (@felixtrz)
- Add support for Quest 3 controllers (@dmarcos, @felixtrz)
- New obb-collider implementing oriented bounding box colliders (@dmarcos)
- Improve hand-trackin-controls pinch logic (@dmarcos)
- Add anisotropy option to material and renderer (#5309) (@mrxz)
- Linter improvements (#5342) (@diarmidmackenzie)
- Add loopStart and loopEnd properties to sound component to play loops (#5364) (@JonathannJacobs)
- Update to THREE r158 (@felixtrz, @dmarcos) (fix #5369)
- Improve sorting / rendering order (#5332) (@diarmidmackenzie, @mrxz)
- Redesign enter immersive mode UI (@vincentfretin, @msub2, @diarmidmackenzie, @thedart76, @dmarcos)
- Replace the use of getJointPose with fillPoses and fillJointRadii in hand-tracking-controls to avoid memory allocations (#5298) (@mrs)
- Handle conversion from sRGB to Linear-sRGB implicitly instead of calling applyColorCorrection (#5210) (@mrxz, @vincentfretin)
- Add Pico 4 headset controllers support (#5281) (@felixtrz)
- Update URL to basis encoder (#5329) (@vincentfretin)
- Add Spatial Computing UI example (#7ea40c13) (@dmarcos)
- Remove workaround for an old Chrome bug in the context of a-assets (#5335) (@mrxz)
- Unit tests improvements (@mrxz, @dmarcos)
- Consolidate references to the CDN URL in a global variable (#5333) (@diarmidmackenzie)
- Docs improvements (@luc122c, @donmccurdy, @turbotimon, @lainshiHenry, @Rhys-Alexander, @vincentfretin, @dmarcos)
Deprecations
- vr-mode-ui component renamed to xr-mode-ui (@dmarcos)
- GearVR and Daydream support (@vincentfretin, @dmarcos)

用户点评

登录用户的真实使用记录，可按版本和硬件筛选

共 0 条

还没有人点评。第一个说出真实体验的人最有价值。

README 原文

未翻译

在 GitHub 打开

Examples

Find more examples on the homepage, A Week of A-Frame, and WebVR Directory.

Features

:eyeglasses: Virtual Reality Made Simple: A-Frame handles the 3D and WebXR boilerplate required to get running across platforms including mobile, desktop, and all headsets (compatible with a WebXR capable browser) just by dropping in <a-scene>.

:heart: Declarative HTML: HTML is easy to read and copy-and-paste. Since A-Frame can be used from HTML, A-Frame is accessible to everyone: web developers, VR and AR enthusiasts, educators, artists, makers, kids.

:electric_plug: Entity-Component Architecture: A-Frame is a powerful framework on top of three.js, providing a declarative, composable, reusable entity-component structure for three.js. While A-Frame can be used from HTML, developers have unlimited access to JavaScript, DOM APIs, three.js, WebXR, and WebGL.

:zap: Performance: A-Frame is a thin framework on top of three.js. Although A-Frame uses the DOM, A-Frame does not touch the browser layout engine. Performance is a top priority, being battle-tested on highly interactive WebXR experiences.

:globe_with_meridians: Cross-Platform: Build VR and AR applications for any headset compatible with a WebXR capable browser. Don't have a headset or controllers? No problem! A-Frame still works on standard desktop and smartphones.

:mag: Visual Inspector: A-Frame provides a built-in visual 3D inspector with a workflow similar to a browser's developer tools and interface similar to Unity. Open up any A-Frame scene and hit <ctrl> + <alt> + i.

:runner: Features: Hit the ground running with A-Frame's built-in components such as geometries, materials, lights, animations, models, raycasters, shadows, positional audio, tracked controllers. Get even further with community components such as particle systems, physics, multiuser, oceans, mountains, speech recognition, or teleportation!

Usage

Example

Build VR and AR scenes in the browser with just a few lines of HTML! To start playing and publishing now, remix the starter example on:

<html>
  <head>
    <script src="https://aframe.io/releases/1.8.0/aframe.min.js"></script>
  </head>
  <body>
    <a-scene>
      <a-box position="-1 0.5 -3" rotation="0 45 0" color="#4CC3D9"></a-box>
      <a-sphere position="0 1.25 -5" radius="1.25" color="#EF2D5E"></a-sphere>
      <a-cylinder position="1 0.75 -3" radius="0.5" height="1.5" color="#FFC65D"></a-cylinder>
      <a-plane position="0 0 -4" rotation="-90 0 0" width="4" height="4" color="#7BC8A4"></a-plane>
      <a-sky color="#ECECEC"></a-sky>
    </a-scene>
  </body>
</html>

With A-Frame's entity-component architecture, we can drop in community components from the ecosystem (e.g., ocean, physics) and plug them into our objects straight from HTML:

See example

<html>
  <head>
    <script src="https://aframe.io/releases/1.8.0/aframe.min.js"></script>
    <script src="https://cdn.jsdelivr.net/gh/c-frame/[email protected]/dist/aframe-particle-system-component.min.js"></script>
    <script src="https://cdn.jsdelivr.net/gh/c-frame/[email protected]/dist/aframe-extras.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/@fern-solutions/aframe-sky-background/dist/sky-background.umd.min.js"></script>
  </head>
  <body>
    <a-scene>
      <a-entity id="rain" particle-system="preset: rain; color: #24CAFF; particleCount: 5000"></a-entity>

      <a-entity id="sphere" geometry="primitive: sphere"
                material="color: #EFEFEF; shader: flat"
                position="0 0.15 -5"
                light="type: point; intensity: 15.7"
                animation="property: position; easing: easeInOutQuad; dir: alternate; dur: 1000; to: 0 -0.10 -5; loop: true"></a-entity>

      <a-entity id="ocean" ocean="density: 20; width: 50; depth: 50; speed: 4"
                material="color: #9CE3F9; opacity: 0.75; metalness: 0; roughness: 1"
                rotation="-90 0 0"></a-entity>

      <a-sky-background top-color="#EBEBF5" bottom-color="#B9B9D2"></a-sky-background>

      <a-entity id="light" light="type: ambient; color: #888"></a-entity>
    </a-scene>
  </body>
</html>

Builds

To use the latest stable build of A-Frame, include aframe.min.js:

<head>
  <script src="https://aframe.io/releases/1.8.0/aframe.min.js"></script>
</head>

To check out the stable and master builds, see the dist/ folder.

npm

npm install --save aframe
# Or yarn add aframe

import AFRAME from 'aframe';  // e.g., with Webpack or Vite.

Local Development

git clone https://github.com/aframevr/aframe.git  # Clone the repository.
cd aframe && npm install  # Install dependencies.
npm start  # Start the local development server.

And open in your browser http://localhost:8080.

If you want to test the examples in VR, you need to run it with https:

npm run start:https

Look at the "On Your Network (IPv4)" line in the console, and copy and paste the url to https://hmd.link service. Then open the browser in your headset and type hmd.link in the address bar then click on the copied url that will show up if you're connected to the same network as your machine. You will see a message about the page being dangerous because we're using a self-signed certificate, you can ignore that warning and continue to the page.

Generating Builds

npm run dist

Questions

For questions and support, ask on StackOverflow.

Stay in Touch

Hang out with the community
Follow @aframevr on X.

And get in touch with the maintainers!

Contributing

Get involved! Check out the Contributing Guide for how to get started.

You can also support development by buying a gorgeous A-Frame t-shirt with exclusive designs

License

This program is free software and is distributed under an MIT License.

怎么上手

项目说明

最近发版

1.8.0 (June 23, 2026)

Major Changes

Bug fixes

Enhancements

Deprecations

1.7.1 (Apr 1, 2025)

Bug fixes

1.7.0 (Feb 20, 2025)

Major Changes

Bug fixes

Enhancements

1.6.0 (May 23, 2024)

Bug fixes

Performance

Enhancements

Bug fixes

Enhancements

Deprecations

用户点评

README 原文

Examples

Features

Usage

Example

Builds

npm

Local Development

Generating Builds

Questions

Stay in Touch

Contributing

License

相关项目