Alpine LinuxのコンテナでBiomeを動かそうとしたらエラーが出たので対処してみた

2026.01.06

こんにちは。クラウド事業本部の桑野です。
最近、TypeScriptのプロジェクトのリファクタリングを検討するにあたり、リンターとフォーマッターを見直す機会があり、Biomeの採用を考えています。
普段私は、コンテナ × Dev Container で開発環境を構築していることが多く、ベースとなるイメージはAlpineを好んで使っているのですが、そこにBiomeとBiomeのVSCode拡張機能を導入し、保存時に自動でフォーマットしようとしたところ動かないという状況に遭遇しました。
今回はそのトラブルシューティングしたお話を共有します。

https://biomejs.dev/ja/

前提

前回の記事同様、以下の条件で検証しています。

OS：macOS Sequoia バージョン 15.6.1
チップ：Apple M4
Docker Client：28.4.0
Docker Server：28.3.3
Colima：0.8.4
docker compose：2.39.3

Colimaを使ったDocker環境の構築手順については以下の記事をご参照ください。
「手順」と「実践編」の1の手順を実施し、docker環境とdocker composeが使えるようになっていれば準備OKです。

再現手順

今回検証したソースコードは以下のリポジトリに置いています。

1. コンテナの準備

以下3ファイルを作成します。

Dockerfile
docker-compose.yaml
devcontainer.json

それぞれ下記の内容です。

Dockerfile

Node.jsのv24を使っています。
ベースイメージはAlpineです。

FROM node:24.11.0-alpine

WORKDIR /frontend

# pnpmのグローバルディレクトリ設定
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"

# Corepackの有効化
RUN corepack enable

# Claude Code のインストール
RUN pnpm add -g @anthropic-ai/claude-code

RUN apk add --no-cache \
  bash

ENV SHELL=/bin/bash

docker-compose.yaml

services:
  frontend:
    container_name: frontend
    build:
      context: ./dockerfiles
      dockerfile: frontend/Dockerfile
    volumes:
      - ./frontend:/frontend
    tty: true

.devcontainer/devcontainer.json

Dev Containerアクセス時にBiomeの拡張機能がインストールされるようにしています。

{
    "name": "Frontend",
    "service": "frontend",
    "runServices": [
        "frontend"
    ],
    "workspaceFolder": "/frontend",
    "dockerComposeFile": "../../docker-compose.yaml",
    "customizations": {
        "vscode": {
            "extensions": [
                "streetsidesoftware.code-spell-checker",
                "PKief.material-icon-theme",
                "Anthropic.claude-code",
                "pflannery.vscode-versionlens",
                "biomejs.biome" // <- 必須
            ]
        }
    }
}

2. コンテナへのアクセス

リポジトリルートで以下のコマンドを実行します。

docker compose up -d

コンテナが起動したら、frontendというコンテナにアクセスします。

3. TypeScriptの準備

順にコマンドを実行していきます。

# プロジェクト初期化
pnpm init

# TypeScript、nodeの型情報を追加
pnpm add -D typescript @types/node

# tsconfigの初期化
pnpm tsc --init --rootDir src --outDir lib --esModuleInterop --resolveJsonModule --lib es6,dom --module commonjs

参考

4. Biomeの追加

順にコマンドを実行していきます。

# Biomeを追加
pnpm add --save-dev --save-exact @biomejs/biome

# Biomeの設定ファイルを作成
pnpm exec biome init

5. VSCode設定の追加

保存時にBiomeで自動的にフォーマットしてくれるようにsettings.jsonを記述しています。

{
    "editor.minimap.enabled": false,
    "editor.renderWhitespace": "boundary",
    "editor.guides.bracketPairs": true,
    "editor.lineHeight": 1.5,
    "editor.fontSize": 12,
    "editor.tabSize": 2,
    "editor.rulers": [
        80,
        120
    ],
    "editor.formatOnSave": false,
    "editor.defaultFormatter": null,
    "[javascript][typescript][javascriptreact][typescriptreact][json]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "biomejs.biome"
    },
}

実施した手順は以上のとおりです。

遭遇した事象

以下のファイルを作成し、ファイルの保存を行いました。

const single = '1重引用符'
const double = "2重引用符"

Biomeの設定ファイルではJavaScript系列のファイルは"quoteStyle": "double"となっているため、上の変数singleはダブルクォーテーションに変換されるはずなのですが、結果としてターミナルでは以下のエラーが出力されました。

[warning] 🔍 Could not determine the version of Biome binary at "/frontend/node_modules/.pnpm/@biomejs+cli-linux-arm64@2.3.11/node_modules/@biomejs/cli-linux-arm64/biome"
[error] Unable to find the Biome binary.

どうやらBiomeのバイナリが見つからないという内容のようです。
しかし、パスを追っていくとバイナリが見つかるため、本質的には別の要因が考えられるのではないかと感じました。

ちなみに下記を実行するとちゃんとフォーマットが実行されるため、VSCode拡張機能が怪しいのではないかと考えています。

pnpm biome format ./src/sample.ts --write

# 結果
Formatted 1 file in 5ms. Fixed 1 file.

解消方法

以下どちらかを実施することで解消します。

settings.jsonで使用するバイナリを設定する（推奨）

{
  "biome.lsp.bin": "/frontend/node_modules/.pnpm/@biomejs+cli-linux-arm64-musl@2.3.11/node_modules/@biomejs/cli-linux-arm64-musl/biome"
}

今回はVSCode拡張機能の問題だったため、こちらで対応するのが良いかと思いました。

コンテナにgcompatをインストールする

コンテナで以下のコマンドを実行することでも解消しました。

apk add --no-cache gcompat

コンテナにgcompatをインストールをしています。
Dockerfileにも同様のコマンドを追記しておくと、毎回実行する手間が省けます！

FROM node:24.11.0-alpine

WORKDIR /frontend

# pnpmのグローバルディレクトリ設定
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"

# Corepackの有効化
RUN corepack enable

# Claude Code のインストール
RUN pnpm add -g @anthropic-ai/claude-code

RUN apk add --no-cache \
  bash \
  # ここに追加
  gcompat 

ENV SHELL=/bin/bash

Biomeバイナリはmuslも対応しているため、今回はこちらでなくても良いと考えています。

原因

VSCode拡張機能がデフォルトでglibcのバイナリを参照するためです。
エラーの内容をもう一度見てみましょう。

[warning] 🔍 Could not determine the version of Biome binary at "/frontend/node_modules/.pnpm/@biomejs+cli-linux-arm64@2.3.11/node_modules/@biomejs/cli-linux-arm64/biome"
[error] Unable to find the Biome binary.

AlpineではmuslというC言語の共通ライブラリを使用するため、Biomeのバイナリもそれに対応する@biomejs+cli-linux-arm64-musl@2.3.11を使用します。
しかし、VSCode拡張機能では@biomejs+cli-linux-arm64@2.3.11というglibc版のバイナリへのパスを参照するのがデフォルト設定なようです。
その違いによって「対応する Biomeのバイナリが見つからないよ」と出力されていたのではないかと考えています。

以下の記事がなんでそうなっているのかという背景について触れられており、すごく納得感がありました。

ちなみにgcompatをインストールすると解決するのは、gcompatがAlpineなどのmusl libcシステムでglibcを使用するための互換APIを提供しているからです。

まとめ

いかがだったでしょうか？
普段何気なくAlpineをベースにしたコンテナイメージを使っていましたが、glibc問題というのがあることを今回初めて知りました。
今回の問題はBiomeに限らず、他のRust製ツールでも発生する可能性があります。
最近、高速なRust製のツールが増えつつあり、開発体験がどんどん良くなっています。Alpineをベースイメージとして使用する際は、「バイナリのプログラムがC言語の共通ライブラリの違いで動かないことがある」ということを頭の片隅に置いて利用していかないといけないなと考えています。
最後までご覧いただきありがとうございました。

Alpine LinuxのコンテナでBiomeを動かそうとしたらエラーが出たので対処してみた

前提

再現手順

1. コンテナの準備

2. コンテナへのアクセス

3. TypeScriptの準備

4. Biomeの追加

5. VSCode設定の追加

遭遇した事象

解消方法

原因

まとめ

関連記事

AWSで探す

注目のテーマ

プロダクトやサービスで探す

特集やシリーズから探す

EVENTS