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

Q: PixiJS 場景一定要自己建立 canvas 嗎？

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

Q: PIXI.Application 的 width 和 CSS width 有什麼不同？

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

Q: PixiJS 場景要怎麼避免畫面被拉伸？

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

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

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

PixiJS 場景設定的基本流程是先把 PixiJS、SystemJS 與 jQuery 放進 HTML 入口檔，再用 PIXI.Application 建立 canvas 遊戲畫面。完成場景後，可以把 canvas 放進指定容器，並用 resize 邏輯讓遊戲畫面在不同螢幕尺寸下維持比例與置中。

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

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

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

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width">
  <title>Test</title>
  <link rel="stylesheet" type="text/css" href="assets/style.css">
  <script src="lib/system.js"></script>
  <script src="lib/jquery.min.js"></script>
  <script src="lib/pixi.min.js"></script>
</head>
<body>
</body>
</html>

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

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 官方基礎範例中的建立方式如下：

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。

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 可以整理成下表：

參數	型別	預設值	用途
`autoStart`	`boolean`	`true`	是否自動啟動 ticker
`width`	`number`	`800`	renderer view 的寬
`height`	`number`	`600`	renderer view 的高
`view`	`HTMLCanvasElement`	無	指定遊戲場景要使用的 canvas；未傳入時會新建 canvas
`transparent`	`boolean`	`false`	是否讓 canvas 背景透明，可看到底下物件
`antialias`	`boolean`	`false`	是否開啟防鋸齒
`preserveDrawingBuffer`	`boolean`	`false`	是否保留繪圖緩衝，方便使用 `toDataURL()`
`resolution`	`number`	`1`	renderer 解析度
`forceCanvas`	`boolean`	`false`	即使存在 WebGL 也強制使用 Canvas
`backgroundColor`	`number`	`0x000000`	場景背景顏色
`clearBeforeRender`	`boolean`	`true`	每次繪圖前是否先清除 canvas
`roundPixels`	`boolean`	`false`	是否用 `Math.floor()` 處理圖像位置
`forceFXAA`	`boolean`	`false`	強制使用 FXAA，速度可能較快但品質可能低於 WebGL 預設效果
`legacy`	`boolean`	`false`	提高與舊裝置相容性
`powerPreference`	`string`	無	傳給 WebGL 的效能偏好，雙顯卡設備可用來指定效能傾向
`sharedTicker`	`boolean`	`false`	是否使用共用的 `PIXI.ticker.shared`
`sharedLoader`	`boolean`	`false`	是否使用共用的 `PIXI.loaders.shared`

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

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

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

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

<body>
<div id="gameContainer">
  <canvas id="gameCanvas"></canvas>
</div>
</body>

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

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：

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()：

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() 加上下面兩行：

// 設定遊戲大小隨視窗大小改變
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、最後處理螢幕縮放。這個順序適合先確認渲染成功，再逐步接上素材與遊戲邏輯。

步驟	檔案	重點
1	`index.html`	載入 `system.js`、`jquery.min.js`、`pixi.min.js`
2	`gulpfile.js`	把 library 複製到 `build/lib`
3	`index.html`	建立 `#gameContainer` 與 `#gameCanvas`
4	`Main.ts`	用 `PIXI.Application` 指定 canvas 並建立 stage
5	`Main.ts`	寫 `onResize()`，讓 canvas 等比例置中縮放

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

常見問題

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 結構。）

關於作者

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

首次發布：2018-10-29