Contents
2025 年版 Rust → WebAssembly 開発環境の構築ガイド
このドキュメントは、Windows・macOS・Linux 各プラットフォームで必要なツールチェーンを最新状態に揃える手順をまとめたものです。
同じ作業が繰り返し記述されている箇所は共通セクションへ統合し、全体の可読性と保守性を高めました。また、公式ドキュメントに準拠したコマンド表記や、Linux の apt 系で binaryen がパッケージ化されていない場合の代替インストール手順も追記しています。
共通ツールチェーンインストール手順
このセクションでは、Rustup 本体と WebAssembly 用サブツール（wasm-bindgen-cli・wasm-pack）のインストール方法を共通化しています。各 OS のパッケージマネージャで Rustup を導入したら、以下のコマンドで必須クレートを取得してください。
rustup と Cargo ツールチェーンのインストール
| OS | コマンド例 |
|---|---|
| Windows (scoop) | scoop install rustup |
| Windows (Chocolatey) | choco install rustup.install -y |
| macOS (Homebrew) | brew install rustup-init && rustup-init -y |
| Linux (apt / pacman) | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y |
インストール後はシェルを再読み込みし、デフォルトツールチェーンを stable に設定します。
|
1 2 3 |
source $HOME/.cargo/env # 必要に応じて追加 rustup default stable |
WebAssembly 用ターゲットとサブツールの取得
|
1 2 3 4 5 6 7 |
# ターゲット追加（全 OS 共通） rustup target add wasm32-unknown-unknown # Cargo 経由でインストールするサブツール cargo install -f wasm-bindgen-cli cargo install -f wasm-pack |
バージョン確認
すべてのツールが正しく導入されたかを確認するため、以下コマンドを実行してください。エラーが出なければインストールは完了です。
|
1 2 3 4 5 6 |
rustc --version # 例: rustc 1.78.0 (2024‑05‑20) cargo --version # 例: cargo 1.78.0 wasm-opt --version # binaryen が提供する wasm-opt のバージョン wasm-bindgen --version # 例: wasm-bindgen-cli 0.2.92 wasm-pack --version # 例: wasm-pack 0.13.0 |
Windows のセットアップ
Windows 環境では scoop または Chocolatey が一般的です。ここでは、どちらのパッケージマネージャでも同等に動作する手順を示します。
前提条件とインストール概要
まずは rustup と binaryen（wasm-opt を提供）をそれぞれのマネージャで導入し、共通ツールチェーンの設定へ進みます。以下のコマンドは管理者権限が不要な scoop の例です。
scoop を使用する場合
|
1 2 3 4 5 6 7 8 9 10 11 |
# rustup と binaryen のインストール scoop install rustup scoop install binaryen # 以降は共通セクションで実施した手順を再利用 source $HOME/.cargo/env rustup default stable rustup target add wasm32-unknown-unknown cargo install -f wasm-bindgen-cli cargo install -f wasm-pack |
Chocolatey を使用する場合
|
1 2 3 4 5 6 7 8 9 10 11 |
# rustup と binaryen のインストール choco install rustup.install -y choco install binaryen -y # 以降は同様に共通ツールチェーン手順を実行 source $HOME/.cargo/env rustup default stable rustup target add wasm32-unknown-unknown cargo install -f wasm-bindgen-cli cargo install -f wasm-pack |
バージョン確認（再掲）
|
1 2 3 4 5 6 |
rustc --version cargo --version wasm-opt --version wasm-bindgen --version wasm-pack --version |
macOS のセットアップ
macOS では Homebrew がデファクトスタンダードです。公式ドキュメントに合わせ、rustup-init を Homebrew 経由で取得し、インタラクティブなし自動設定を行います。
Homebrew によるインストール手順
|
1 2 3 4 5 6 7 8 9 10 11 |
# rustup と binaryen の取得（1 行で完結） brew install rustup-init && rustup-init -y # 環境変数の再読み込み source $HOME/.cargo/env # ターゲットとサブツールを共通セクションに従ってインストール rustup target add wasm32-unknown-unknown cargo install -f wasm-bindgen-cli cargo install -f wasm-pack |
バージョン確認（macOS 共通）
|
1 2 3 4 5 |
rustc --version wasm-opt --version wasm-bindgen --version wasm-pack --version |
Linux のセットアップ（apt / pacman）
Linux ではディストリビューションごとにパッケージ管理方式が異なります。本稿では Ubuntu/Debian 系 (apt) と Arch 系 (pacman) を対象に手順を示し、binaryen が公式リポジトリに無い環境への代替インストール方法も解説します。
前提条件と共通インストールフロー
- 必要な開発ツールと
curlをインストール rustupのスクリプト実行で Rust ツールチェーンを取得- ターゲット追加・サブツール導入は 共通セクション と同様
以下、OS 別に細分化しています。
apt 系 (Ubuntu / Debian)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
# 基本開発パッケージのインストール sudo apt update sudo apt install -y curl build-essential libssl-dev pkg-config # rustup の導入 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y source $HOME/.cargo/env rustup default stable rustup target add wasm32-unknown-unknown # binaryen がリポジトリに無い場合の代替手順 if ! dpkg -l | grep -q binaryen; then echo "binaryen パッケージが見つかりません。GitHub Release からバイナリを取得します。" LATEST=$(curl -s https://api.github.com/repos/WebAssembly/binaryen/releases/latest | \ grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/') wget "https://github.com/WebAssembly/binaryen/releases/download/${LATEST}/binaryen-${LATEST}-x86_64-linux.tar.gz" tar -xzf binaryen-*-x86_64-linux.tar.gz sudo cp binaryen-*/bin/wasm-opt /usr/local/bin/ rm -rf binaryen-* fi # Cargo 経由でサブツールをインストール（共通手順） cargo install -f wasm-bindgen-cli cargo install -f wasm-pack |
pacman 系 (Arch Linux / Manjaro)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
sudo pacman -Sy --needed base-devel curl git # rustup の導入 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y source $HOME/.cargo/env rustup default stable rustup target add wasm32-unknown-unknown # binaryen は公式リポジトリに存在 sudo pacman -S --needed binaryen # サブツールのインストール（共通手順） cargo install -f wasm-bindgen-cli cargo install -f wasm-pack |
バージョン確認（Linux 共通）
|
1 2 3 4 5 |
rustc --version wasm-opt --version # 取得方法に応じてパスが通っているか確認 wasm-bindgen --version wasm-pack --version |
Rust と WebAssembly ターゲットの基本設定
この章では、WebAssembly 用ターゲットの追加と 必須クレートの記述 方法を解説します。正しく設定しておくことで、後続のビルドやデバッグがシームレスに行えるようになります。
ターゲット追加（全プラットフォーム共通）
|
1 2 |
rustup target add wasm32-unknown-unknown |
Cargo.toml に必要な依存関係を記述
2025 年時点での最新版は wasm-bindgen 0.2.92 が推奨です。プロジェクトルートの Cargo.toml に以下を書き込みます。
|
1 2 3 |
[dependencies] wasm-bindgen = "0.2" |
#[wasm_bindgen] アトリビュートの基本
#[wasm_bindgen] マクロは Rust 側の関数や構造体を JavaScript から呼び出せるようにラップします。最小サンプルは次の通りです。
|
1 2 3 4 5 6 7 |
use wasm_bindgen::prelude::*; #[wasm_bindgen] pub fn greet(name: &str) -> String { format!("Hello, {}!", name) } |
pubが必須で、外部からアクセス可能になります。- 引数・戻り値は
String、&str、整数型など wasm-bindgen が自動変換できる型 に限定してください。
この関数をビルドすれば、ブラウザ上の JavaScript から greet("World") と呼び出せます。
プロジェクト作成とデバッグビルド
実際にコードを書きながら デバッグビルド を行う手順を紹介します。パニック時にスタックトレースがコンソールへ出力されるよう設定することがポイントです。
1. プロジェクトの雛形生成
|
1 2 3 |
cargo new --lib my_wasm cd my_wasm |
Cargo.toml に先ほど示した wasm-bindgen と、デバッグ時に便利な console_error_panic_hook を追加します。
|
1 2 3 4 |
[dependencies] wasm-bindgen = "0.2" console_error_panic_hook = "0.1" |
2. エントリポイントでパニックフックを有効化
src/lib.rs に以下コードを書き込みます。#[wasm_bindgen(start)] はモジュールがロードされた瞬間に実行され、フック設定だけでなく初期化処理も書けます。
|
1 2 3 4 5 6 7 8 9 |
use wasm_bindgen::prelude::*; use console_error_panic_hook; #[wasm_bindgen(start)] pub fn init() { // パニック時にコンソールへスタックトレースを出力するフックを設定 console_error_panic_hook::set_once(); } |
3. デバッグビルドの実行
|
1 2 3 |
cargo build --target wasm32-unknown-unknown --debug # 出力: target/wasm32-unknown-unknown/debug/my_wasm.wasm |
4. wasm-bindgen による JavaScript バインディング生成
|
1 2 3 |
wasm-bindgen target/wasm32-unknown-unknown/debug/my_wasm.wasm \ --out-dir ./pkg --target web |
./pkg ディレクトリに my_wasm.js と my_wasm_bg.wasm が生成されます。
5. ローカルサーバで確認
次章「ローカルテスト・デプロイ」で紹介する軽量サーバを起動し、ブラウザのコンソールで greet("Rust") を呼び出すと期待通りの文字列が表示されます。パニックを意図的に発生させれば、console_error_panic_hook がスタックトレースを出力することも確認できます。
リリースビルドと最適化フロー
本番環境向けには サイズ削減 と 実行速度の最大化 が求められます。以下では cargo build --release に続くバイナリ最適化手順を詳述します。
1. リリースビルド
|
1 2 3 |
cargo build --target wasm32-unknown-unknown --release # 出力: target/wasm32-unknown-unknown/release/my_wasm.wasm |
2. wasm-bindgen バインディング生成（リリース版）
|
1 2 3 4 |
wasm-bindgen target/wasm32-unknown-unknown/release/my_wasm.wasm \ --out-dir ./pkg --target web # 生成物: pkg/my_wasm.js, pkg/my_wasm_bg.wasm |
3. binaryen の wasm-opt -Oz によるサイズ圧縮
-Oz は「サイズ優先」の最高圧縮モードです。最適化前後のファイルサイズ比較例を表に示します。
|
1 2 |
wasm-opt -Oz ./pkg/my_wasm_bg.wasm -o ./pkg/my_wasm_opt.wasm |
| ビルド種別 | ファイル名 | サイズ (2025‑03 時点) |
|---|---|---|
| デバッグ | my_wasm_bg.wasm |
182 KB |
| リリース未圧縮 | my_wasm_bg.wasm (release) |
94 KB |
| リリース + 圧縮 | my_wasm_opt.wasm |
58 KB |
約 38% のサイズ削減が実現でき、ロード時間の短縮につながります。
4. wasm-pack を使ったワンステップビルド
wasm-pack は npm パッケージ化まで自動で行える便利ツールです。リリースモードで最適化済みバイナリを生成する例は次の通りです。
|
1 2 3 |
wasm-pack build --target web --release \ --out-dir pkg --out-name my_wasm |
生成される pkg/ の構成は以下のようになります。
|
1 2 3 4 5 |
pkg/ ├─ my_wasm.js # JavaScript ラッパー ├─ my_wasm_bg.wasm # 圧縮済み WebAssembly バイナリ └─ package.json # npm 用メタ情報 |
このディレクトリをそのまま npm publish すれば、他プロジェクトで import * as wasm from "my_wasm" と利用できます。
ローカルテスト・デプロイ・CI/CD の実践
ビルドが完了したら、ローカル環境で動作確認し、続いて自動化パイプラインへ組み込む流れを解説します。ここまでの手順が正しく機能すれば、数分で本番デプロイが可能です。
1. ローカルサーバで動作確認
静的ファイルだけで完結する軽量サーバは以下のいずれかで起動できます。どちらも追加インストール不要（Node.js が必要なのは serve のみ）です。
| 方法 | コマンド例 |
|---|---|
Node.js の serve (npm 必要) |
npm install -g serve && serve ./pkg --single |
| Python 標準モジュール | cd pkg && python -m http.server 8000 |
ブラウザで http://localhost:8000 にアクセスし、コンソールに Hello, … と表示されれば成功です。デバッグビルドの場合は意図的にパニックを起こすコードを書き、console_error_panic_hook がスタックトレースを出力することも確認してください。
2. GitHub Actions による自動ビルド・最適化
以下は Ubuntu ランナー 上で実行されるシンプルな workflow の例です。binaryen が apt に無い環境でも代替インストールを行うステップが含まれています。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 |
name: Build WASM on: push: branches: [ main ] jobs: build-wasm: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 # Rust toolchain のセットアップ - name: Install Rustup & target run: | curl https://sh.rustup.rs -sSf | sh -s -- -y source $HOME/.cargo/env rustup default stable rustup target add wasm32-unknown-unknown # binaryen のインストール（apt が無い場合はバイナリ取得） - name: Install Binaryen run: | sudo apt-get update && sudo apt-get install -y binaryen || { LATEST=$(curl -s https://api.github.com/repos/WebAssembly/binaryen/releases/latest | grep tag_name | cut -d '"' -f4) wget "https://github.com/WebAssembly/binaryen/releases/download/${LATEST}/binaryen-${LATEST}-x86_64-linux.tar.gz" tar -xzf binaryen-*-x86_64-linux.tar.gz sudo cp binaryen-*/bin/wasm-opt /usr/local/bin/ } # Cargo でビルド → wasm-bindgen → wasm-opt - name: Build Release WASM run: | source $HOME/.cargo/env cargo build --release --target wasm32-unknown-unknown wasm-bindgen target/wasm32-unknown-unknown/release/my_wasm.wasm \ --out-dir ./pkg --target web wasm-opt -Oz ./pkg/my_wasm_bg.wasm -o ./pkg/my_wasm_opt.wasm # アーティファクトとして保存（次工程でデプロイに使用） - name: Upload WASM artifact uses: actions/upload-artifact@v3 with: name: wasm-package path: pkg/ |
この workflow は コードプッシュ → ビルド → バインディング生成 → サイズ圧縮 までを自動化し、pkg/ ディレクトリをアーティファクトとして保存します。
3. 静的ホスティングへのデプロイ例
| 方法 | 手順の要点 |
|---|---|
| SFTP | scp -r pkg/* user@host:/var/www/site で直接アップロード。サーバ側は静的ファイルを配信できるように設定だけで完了。 |
| Netlify | GitHub リポジトリと連携し、netlify.toml に publish = "pkg" を記載すればプッシュ時に自動デプロイ。 |
| Vercel | vercel --prod 実行後、vercel.json の "outputDirectory": "pkg" でビルド成果物を指定。 |
いずれの場合も配信対象は pkg/ ディレクトリだけ に限定することで、余計なファイルが混入せず最小サイズで公開できます。
次のステップ
- 本記事の手順通りにサンプルプロジェクトをローカルでビルドし、デバッグ版とリリース版のサイズ・実行速度差異を体感してください。
- GitHub Actions の workflow を有効化すれば、
push → ビルド → デプロイが自動化され、継続的に最適化された Wasm が生成されます。 - さらに高度な最適化が必要なら、
wasm-pack build --scope your-org --mode no-installやrollup-plugin-wasm、webpack wasm-loaderといったエコシステムツールを組み合わせてコード分割や JavaScript バンドラとの統合を検討してください。
以上の流れを踏めば、2025 年版ツールチェーンに完全対応した Rust → WebAssembly 開発フロー が確立できます。実務プロジェクトでも個人学習でも、ぜひ本手順を活用して高速かつ軽量な Web アプリケーションを構築してください。