lsiodev/emulatorjs

linuxserver/emulatorjs 镜像文档

镜像概述和主要用途

linuxserver/emulatorjs 是由 LinuxServer.io 团队开发的 Docker 镜像，提供基于浏览器的网页版复古游戏机模拟功能。该镜像集成了 Libretro 和 EmulatorJS 混合模拟器，支持多种复古游戏主机，可在几乎任何设备的浏览器中运行。通过简单的配置，用户可以搭建自托管的复古游戏平台，管理游戏 ROM 和艺术资源，并通过网页界面便捷地浏览和启动游戏。

核心功能和特性

• 多平台支持：支持 x86-64 和 arm64v8 架构，可在多种设备上部署
• 丰富的模拟器集成：混合使用 Libretro 和 EmulatorJS 核心，支持多种复古游戏主机
• Web 管理界面：提供 ROM 和艺术资源管理界面，简化游戏库配置流程
• 用户权限控制：通过 PUID/PGID 实现简单的用户映射，避免权限问题
• 静态网页生成：可将生成的游戏前端静态文件部署到任何 Web 服务器或对象存储
• 定期更新：包含应用定期更新、每周基础 OS 更新和安全更新
• 自定义基础镜像：基于 s6 overlay 定制的基础镜像，优化容器运行效率

支持的游戏主机

该镜像支持以下复古游戏主机的 ROM：3do、arcade、atari2600、atari7800、colecovision、doom、gb、gba、gbc、jaguar、lynx、msx、n64、nds、nes、ngp、odyssey2、pce、psx、sega32x、segaCD、segaGG、segaMD、segaMS、segaSaturn、segaSG、snes、vb、vectrex、ws

使用场景和适用范围

• 个人复古游戏收藏：搭建个人复古游戏库，在浏览器中随时游玩经典游戏
• 家庭娱乐中心：通过智能电视或机顶盒的浏览器访问，实现家庭共享游戏体验
• 教育场景：用于游戏历史教学或复古游戏开发学习
• 低配置设备使用：在性能有限的设备上通过浏览器运行轻量级复古游戏
• 静态网站部署：生成静态游戏前端后，可部署到任何 Web 服务器，脱离容器独立运行

使用方法和配置说明

前置要求

• Docker 或 Docker Compose 环境
• 至少 1GB 可用内存（运行 CD 类游戏建议更高配置）
• 用于存储 ROM 和配置的持久化存储路径

Docker Compose 部署（推荐）

yaml
---
version: "2.1"
services:
  emulatorjs:
    image: lscr.io/linuxserver/emulatorjs:latest
    container_name: emulatorjs
    environment:
      - PUID=1000         # 用户ID，使用 `id your_user` 命令获取
      - PGID=1000         # 组ID，使用 `id your_user` 命令获取
      - TZ=Etc/UTC        # 时区，如 Asia/Shanghai
      - SUBFOLDER=/       # 反向代理子文件夹，可选
    volumes:
      - /path/to/config:/config  # 配置文件存储路径
      - /path/to/data:/data      # ROM和艺术资源存储路径
    ports:
      - 3000:3000        # 管理界面端口
      - 80:80            # 游戏前端端口
      - 4001:4001        # IPFS对等端口，可选
    restart: unless-stopped

Docker CLI 部署

bash
docker run -d \
  --name=emulatorjs \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e SUBFOLDER=/ `#可选` \
  -p 3000:3000 \
  -p 80:80 \
  -p 4001:4001 `#可选` \
  -v /path/to/config:/config \
  -v /path/to/data:/data \
  --restart unless-stopped \
  lscr.io/linuxserver/emulatorjs:latest

参数说明

应用设置

1. 初始配置：

   • 容器启动后，通过 http://yourhost:3000 访问管理界面
   • 点击下载默认艺术资源和配置，将在 /data 目录下创建基础目录结构

2. 添加游戏ROM：

   • 将ROM文件放入 /data/<主机名>/roms 目录（主机名需使用支持的游戏主机文件夹名）
   • 例如：NES游戏放入 /data/nes/roms 目录

3. 访问游戏前端：

   • 通过 http://yourhost:80 访问游戏前端界面
   • 使用游戏手柄或键盘方向键浏览菜单和启动游戏

4. 控制器使用：

   • 推荐使用标准游戏手柄（如Xbox手柄）
   • Xbox用户：启动游戏后按"查看按钮"（两个小方块）几次，确保B键不触发浏览器"返回"操作
   • 长按"菜单按钮"（三横线）3秒可退出控制器模式，返回浏览器控制

5. 静态文件提取：

   • 生成的游戏前端静态文件位于容器内 /emulatorjs/frontend 目录
   • 可将此目录内容复制到其他Web服务器独立部署

注意事项

• 性能考虑：浏览器中运行的模拟器性能有限，不建议期望达到原生硬件水平
• CD游戏限制：Xbox Edge浏览器对大型CD游戏（超过450MB）支持有限
• 存档存储：游戏存档存储在浏览器本地存储中，更换主机IP或端口会导致存档丢失
• Libretro菜单：Libretro核心可通过组合键（Start+Select+L+R）访问设置菜单
• 声音问题：部分模拟器可能存在声音卡顿问题，属于当前技术限制

支持信息

• 容器shell访问：docker exec -it emulatorjs /bin/bash
• 实时日志查看：docker logs -f emulatorjs
• 容器版本信息：docker inspect -f '{{ index .Config.Labels "build_version" }}' emulatorjs
• 镜像版本信息：docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/emulatorjs:latest

更新方法

Docker Compose 更新

bash
# 拉取最新镜像
docker-compose pull emulatorjs

# 更新容器
docker-compose up -d emulatorjs

# 清理旧镜像
docker image prune

Docker CLI 更新

bash
# 拉取最新镜像
docker pull lscr.io/linuxserver/emulatorjs:latest

# 停止并删除当前容器
docker stop emulatorjs
docker rm emulatorjs

# 使用原参数重新创建容器
docker run -d [原参数] lscr.io/linuxserver/emulatorjs:latest

# 清理旧镜像
docker image prune

支持的架构