PixiJS 場景設定教學：Application、Canvas 與自動縮放

PixiJS 專案需要先載入哪些 library？

PixiJS 專案在這份 2018 年筆記中使用 PixiJS、SystemJS 與 jQuery。PixiJS 負責渲染遊戲畫面，SystemJS 負責載入編譯後的 JavaScript 模組，jQuery 則用來取得 DOM 元素。

先新增一個 `index.html` 入口檔，把需要的 CSS 與 library 加進頁面：

```html

```

如果直接打開 HTML，瀏覽器會顯示找不到檔案。這時可以在 `gulpfile.js` 增加一個 `libs` task，把專案需要的 library 複製到 `build/lib`：

```js

gulp.task('libs', () => {

return gulp

.src([

'node_modules/jquery/dist/jquery.min.js',

'node_modules/jquery/dist/jquery.min.map',

'node_modules/systemjs/dist/system-polyfills.js',

'node_modules/systemjs/dist/system-polyfills.js.map',

'node_modules/systemjs/dist/system.js',

'node_modules/systemjs/dist/system.js.map',

'node_modules/pixi.js/dist/pixi.min.js',

'node_modules/pixi.js/dist/pixi.min.js.map'

])

.pipe(gulp.dest("build/lib"));

});

```

這樣每次編譯時，gulp 就會自動把使用到的 library 放進目標資料夾。

PIXI.Application 怎麼建立基本遊戲場景？

`PIXI.Application` 可以建立 PixiJS 的 canvas 遊戲畫面，並提供 renderer、stage、ticker 等常用入口。最小範例只需要設定寬、高與背景色，再把 `app.view` 加到頁面中。

PixiJS 官方基礎範例中的建立方式如下：

```js

var app = new PIXI.Application(800, 600, {backgroundColor : 0x1099bb});

document.body.appendChild(app.view);

```

`PIXI.Application` 這個類別有兩種建構子寫法：一種把寬高放在前兩個參數，另一種把設定集中放進 options 物件。PixiJS v4 之後，官方把相關參數整合進 options 物件，使用時只需要傳入專案真的要設定的值；先傳入寬高的寫法主要是為了兼容舊版。

如果兩邊都傳入相同屬性，會以 options 裡的值為主。下面這段程式雖然前面傳入 `960`，但因為 options 裡設定了 `width: 100`，實際建立的場景寬度會是 `100`。

```js

new PIXI.Application(960, 540, {width:100, backgroundColor : 0x000000, view: gameCanvasContext});

```

PIXI.Application options 常用參數有哪些？

`PIXI.Application` options 用來控制 canvas 尺寸、背景、透明度、解析度、渲染模式與 ticker/loader 共用設定。建立 PixiJS 場景時，先設定 `width`、`height`、`backgroundColor` 與 `view` 通常就足夠。

常用 options 可以整理成下表：

我通常會先把畫面尺寸和實際 CSS 縮放分開：`Application` 負責遊戲內部座標系，CSS 負責瀏覽器視窗中的顯示大小。這樣後面處理不同螢幕比例時比較不會互相牽制。

如何在專案中指定 PixiJS 使用既有 canvas？

指定既有 canvas 的好處是可以在 HTML 與 CSS 中控制容器位置。PixiJS 只負責把畫面畫進 `#gameCanvas`，頁面排版則交給 `#gameContainer` 和 CSS 管理。

先在 `index.html` 加上一個容器與 canvas：

```html

```

接著建立 `Main.ts`，在 `initGame()` 裡取得 `#gameCanvas`，再把它傳給 `PIXI.Application` 的 `view`：

```ts

import Application = PIXI.Application;

// 將 application 設定為 export，這樣可以在專案的任何地方取到這個元件

export let application:Application

/

• 主要的 client application.

*

*/

export class Main {

public initGame() {

// 設定場景

let gameCanvasContext = (< HTMLCanvasElement >jQuery("#gameCanvas")[0]);

application = new PIXI.Application(960, 540, {width:100,backgroundColor : 0x000000, view: gameCanvasContext});

// 貼一張圖片

var bunny = PIXI.Sprite.fromImage('assets/bunny.png');

bunny.x = application.screen.width / 2;

bunny.y = application.screen.height / 2;

application.stage.addChild(bunny);

}

}

```

這段程式先建立 PixiJS application，再用 `PIXI.Sprite.fromImage()` 放一張 `bunny.png` 到舞台中央。`application.stage.addChild(bunny)` 是把 Sprite 加進 PixiJS 顯示清單，之後才會被 renderer 畫出來。

SystemJS 要如何啟動 PixiJS Main 類別？

SystemJS 可以在瀏覽器中載入編譯後的 JavaScript 模組。這份專案會在頁面 ready 後設定 `baseURL` 與副檔名，再 `import('Main')` 執行 `initGame()`。

在 `index.html` 加上下面這段 JavaScript：

```js

var game;

$(function () {

// 設定要載入的 js 位置與副檔名

SystemJS.config({

baseURL: "/",

packages: {

"/": { defaultExtension: "js" }

}

});

// 載入 Main.js，載完後執行裡面的某個 func

SystemJS.import('Main').then(function (m) {

m.Main.prototype.initGame();

});

});

```

打開瀏覽器後，就可以看到 PixiJS 場景已經建立，畫面中間會出現測試用的 bunny 圖片。

這份寫法是舊版 TypeScript 與 SystemJS 專案常見的啟動方式。新專案如果使用 Vite、Webpack 或其他 bundler，入口通常會改成直接從 `main.ts` 匯入並執行初始化函式。

PixiJS canvas 如何隨螢幕大小置中縮放？

PixiJS canvas 可以用視窗寬高計算縮放比例，再改變 `application.view.style` 的位置與顯示尺寸。關鍵是用 `Math.min()` 保持固定比例，避免遊戲畫面被拉伸變形。

前面的成果右下方還有許多空白。若沒有特別對 canvas 做縮放，canvas 會一直維持相同尺寸，這樣在不同平台與不同螢幕尺寸上不容易順利呈現遊戲畫面。

在 `Main.ts` 加上 `onResize()`：

```ts

public onResize() {

var w = window.innerWidth;

var h = window.innerHeight;

var scale = Math.min(w/860,h/540);

application.view.style.left = (w-scale*860)/2 + "px";

application.view.style.top = (h-scale*540)/2 + "px";

application.view.style.width = scale*860 + "px";

application.view.style.height = scale*540 + "px";

}

```

再在 `initGame()` 加上下面兩行：

```ts

// 設定遊戲大小隨視窗大小改變

this.onResize();

window.onresize = this.onResize;

```

完成後，遊戲畫面會永遠置中，並自動縮放到適合螢幕的大小。

這裡有一個實務細節要注意：`new PIXI.Application(960, 540, ...)` 的內部尺寸和 `onResize()` 裡的 `860/540` 不一致。若正式專案要維護固定比例，建議抽成共用常數，例如 `GAME_WIDTH` 與 `GAME_HEIGHT`，避免後續座標、縮放與碰撞範圍出現不一致。

PixiJS 場景設定流程可以怎麼整理？

PixiJS 場景設定可以拆成五步：準備 library、建立 HTML canvas、初始化 `PIXI.Application`、加入第一個 Sprite、最後處理螢幕縮放。這個順序適合先確認渲染成功，再逐步接上素材與遊戲邏輯。

今日成果包含兩個檔案：一個可啟動 PixiJS 場景的 `index.html`，以及一個集中初始化遊戲畫面的 `Main.ts`。下一步通常會接素材載入流程，避免圖片在場景建立後才臨時載入。

延伸閱讀

• PixiJS 介紹：2D WebGL 遊戲引擎適合做什麼？
• PixiJS 載入素材教學：Loader、Spritesheet 與進度事件
• PixiJS 音樂音效設定：用 Howler.js 管理遊戲音效
• PixiJS 按鈕製作基礎：Sprite 互動、ButtonBase 與靜音切換
• PixiJS 按鈕 Tween 動態：用 GSAP 做縮放回彈效果

常見問題

QPixiJS 場景一定要自己建立 canvas 嗎？

PixiJS 場景不一定要自己建立 canvas。未指定 `view` 時，`PIXI.Application` 會建立新的 canvas；如果想用 HTML 與 CSS 控制位置，建議先在頁面建立 canvas，再透過 `view` 傳給 `PIXI.Application`。

QPIXI.Application 的 width 和 CSS width 有什麼不同？

`PIXI.Application` 的 `width` 代表遊戲內部渲染尺寸，CSS `width` 代表瀏覽器畫面上的顯示尺寸。做等比例縮放時，通常保留固定內部尺寸，再調整 canvas 的 CSS 顯示大小。

QPixiJS 場景要怎麼避免畫面被拉伸？

PixiJS 場景可以用 `Math.min(windowWidth / gameWidth, windowHeight / gameHeight)` 計算縮放比例。這樣寬和高會用同一個比例縮放，遊戲畫面就不會被拉寬或壓扁。

Q舊版 PixiJS 的 `fromImage()` 還能用嗎？

`PIXI.Sprite.fromImage()` 是舊版 PixiJS 常見寫法。維護 2018 年左右的專案可以照版本保留；新專案應先查目前 PixiJS 版本文件，改用對應的 `Sprite.from()` 或 Assets 載入流程。

QSystemJS 是 PixiJS 必要工具嗎？

SystemJS 不是 PixiJS 必要工具。這份筆記使用 SystemJS 是當時專案的模組載入方式；現在的新 PixiJS 專案常見做法是用 Vite、Webpack 或其他 bundler 管理入口與模組。

參考資料

• PixiJS Basics 範例：<https://pixijs.com/8.x/examples/basic/container>
• PixiJS Application API：<https://pixijs.download/release/docs/app.Application.html>
• MDN HTMLCanvasElement.toDataURL()：<https://developer.mozilla.org/zh-TW/docs/Web/API/HTMLCanvasElement/toDataURL>

最後更新

2026-08-28（2018-10-29 發布的 PixiJS 場景設定筆記，本文保留原始實作脈絡並補上 GEO 結構。）

關於作者 {#author}

Claire Chang ｜ 企業 AI 導入與流程轉型顧問。專注於 AI Agent 架構設計、ERP 系統整合與企業 AI 治理。

首次發布：2018-10-29