Photoshop│JavaScriptでPSDを読み書きする方法｜ag-psd（Node.js）

ag-psd は、JavaScript（Node.js とブラウザ）で PSD を読み書きできる、MIT ライセンスのライブラリです。

Photoshop が無くても、レイヤーの一覧を取り出したり、レイヤーを組んだ PSD を作ったり、文字レイヤーの文字を書き換えたりできます。

• 入れ方：npm i ag-psd canvas（Node.js で画像を扱うには canvas も要る）
• 読む：readPsd(バッファ)、書く：writePsdBuffer(オブジェクト)
• 文字を書き換えたら invalidateTextLayers: true を付ける（Photoshop で開いたときに描き直させる）
• 33.0.0ではCMYK・インデックスカラーや16/32bitの読み込みに対応。書き出しはRGB・8bit。PSBにも対応するが、形式や圧縮などの制限は別途確認する

この記事の結果は、2026年9月29日に Windows 11 で ag-psd 31.0.2・canvas 3.2.3・Node.js 24.15.0 を使って試したものです。

読み込みの確認には、psd-tools の公式リポジトリにあるテスト用の PSD（MIT）を使いました。

入れる

npm init -y
npm i ag-psd canvas

Node.js では、require(‘ag-psd/initialize-canvas’) で、画像を扱う準備をしてから使います。

レイヤーの一覧を読む

const fs = require('fs');
require('ag-psd/initialize-canvas');
const { readPsd } = require('ag-psd');

const psd = readPsd(fs.readFileSync(process.argv[2]), { skipLayerImageData: true, skipThumbnail: true });
console.log(`${psd.width}x${psd.height}`);
function walk(layers, depth) {
  for (const l of layers || []) {
    const kind = l.children ? 'グループ' : l.text ? '文字' : l.adjustment ? '調整:' + l.adjustment.type : l.placedLayer ? 'スマートオブジェクト' : 'ピクセル';
    console.log('  '.repeat(depth) + `- ${l.name}（${kind}）` + (l.text ? ` 「${l.text.text}」` : ''));
    walk(l.children, depth + 1);
  }
}
walk(psd.children, 0);

skipLayerImageData: trueはレイヤーの画像データを省略する指定です。合成画像も省略したい場合はskipCompositeImageData: trueも指定します。掲載例では合成画像は読み込むため、画像データを一切読まない例ではありません。

テスト用の PSD を読むと、次のように出ました（一部）。

256x256
- Background（ピクセル）
- linked-png（スマートオブジェクト）
- linked-psd（スマートオブジェクト）
- embedded-png（スマートオブジェクト）

256x256
- Background（ピクセル）
- Rectangle 1（ピクセル）
- Brightness/Contrast 1（調整:brightness/contrast）
- Levels 1（調整:levels）
- Curves 1（調整:curves）
- Hue/Saturation 1（調整:hue/saturation）

文字レイヤーはl.text.textで文字を、調整レイヤーはl.adjustment.typeで種類を取り出せました。ただし掲載コードの「ピクセル」は、先に判定した種類以外をまとめた表示です。シェイプなどもそこへ入るため、厳密なレイヤー種別判定には使えません。

PSDを作る

白い背景に、グループと2つの四角のレイヤー（片方は不透明度50%）を入れたPSDを作ります。コードはout.psdへ書き込むため、同名ファイルのない練習用フォルダーで実行してください。既存ファイルがある場合は上書きされます。

const fs = require('fs');
const { createCanvas } = require('canvas');
require('ag-psd/initialize-canvas');           // Node で画像を扱うための準備
const { writePsdBuffer } = require('ag-psd');

function rect(w, h, color) {
  const c = createCanvas(w, h);
  const ctx = c.getContext('2d');
  ctx.fillStyle = color;
  ctx.fillRect(0, 0, w, h);
  return c;
}

const psd = {
  width: 400,
  height: 300,
  children: [
    { name: '背景', canvas: rect(400, 300, '#ffffff') },
    { name: 'パーツ', children: [
      { name: '赤い四角', left: 40, top: 40, canvas: rect(120, 80, '#e03c31') },
      { name: '青い四角', left: 200, top: 120, canvas: rect(150, 120, '#2f6fd6'), opacity: 0.5 },
    ]},
  ],
  canvas: rect(400, 300, '#ffffff'),            // 合成済みのプレビュー（簡略化）
};

fs.writeFileSync('out.psd', writePsdBuffer(psd));
console.log('書き出した', fs.statSync('out.psd').size, 'バイト');

書き出した 22832 バイト

できた PSD を、Python の psd-tools でも読み込めるか確かめました。

400 300
  背景 pixel 255
  パーツ group 255
  赤い四角 pixel 255
  青い四角 pixel 128

レイヤーの名前・グループ・不透明度（255 の半分の 128）が、そのまま読めました。

ここでは合成済みのプレビュー（psd.canvas）を白一色にしているので、プレビューを使うソフトでは白く見えます。

正しいプレビューが要るときは、自分で合成した画像を canvas に入れます。

文字レイヤーの文字を書き換える

const fs = require('fs');
require('ag-psd/initialize-canvas');
const { readPsd, writePsdBuffer } = require('ag-psd');

const psd = readPsd(fs.readFileSync(process.argv[2]));
let count = 0;
(function walk(layers) {
  for (const l of layers || []) {
    if (l.text) { l.text.text = l.text.text.replace(/Line/g, '行'); count++; }
    walk(l.children);
  }
})(psd.children);
if (process.argv[4] === '--drop-resources') delete psd.imageResources;
// 文字を書き換えたら、Photoshop で開いたときに描き直させる
fs.writeFileSync(process.argv[3], writePsdBuffer(psd, { invalidateTextLayers: true }));
console.log('文字レイヤー', count, '個を書き換えた');

このコードは第1引数を入力PSD、第2引数を出力PSDとして扱います。入力と出力を同じパスにせず、既存ファイルのない別の出力先を指定してください。countは文字レイヤーを見つけるたびに増えるため、表示件数は「Line」が実際に置換されたレイヤー数ではありません。文字を書き換えたら、invalidateTextLayers: trueを付けて書き出します。

README によると、ag-psd は文字レイヤーの画像を描き直さないので、Photoshop で開くと更新を求める画面が出ます。

そこで「Update」を選ぶと、Photoshop が文字を描き直します（「No」を選ぶと文字レイヤーが壊れた状態で残る）。

書き出しでエラーになった

テスト用の text.psd をそのまま書き出すと、次のエラーで止まりました。

Error: Invalid boolean value: undefined, key: enab
    at writeOSType (...\ag-psd\dist\descriptor.js:680:23)
    ...
    at Object.write (...\ag-psd\dist\imageResources.js:584:48)

止まったのは、レイヤーではなく、PSD 全体の付加情報（image resources）を書くところでした。

この検証では、psd.imageResourcesを消してから書き出すと、ag-psdとpsd-toolsの両方で、書き換えた文字（行 1 行 2 行 3 and text）を読めました。掲載コードの第3引数--drop-resourcesは、その切り分け用の処理です。通常の保存で一律に指定するものではありません。

ただし、付加情報には解像度などの設定も入っているので、消すと失われるものがあります。

読み込んで書き出す使い方は、PSD によっては失敗するので、元のファイルは必ず残しておきます。また、公式READMEはCanvas経由の読み書きで半透明ピクセルに変化が生じる場合を説明しています。画素の保持が必要ならreadPsdのuseImageData: trueも検討し、元画像との比較が必要です。掲載した文字置換例はそのオプションを指定していません。

できないこと

README には、利用者が送ってきた PSD を扱うときは、大きさやビット数を先に確かめるよう、例とともに書かれています。

Pythonのpsd-toolsとの使い分け

psd-tools の使い方は、psd-toolsの使い方で紹介しています。

psd-tools で見た目が変わる PSD の見分け方は、psd-toolsで書き出せないPSDの見分け方で紹介しています。

まとめ

• npm i ag-psd canvas で入れ、readPsd と writePsdBuffer で読み書きする
• レイヤー・グループ・不透明度は psd-tools でもそのまま読めた
• 文字を変えたら invalidateTextLayers: true。Photoshop で開いたら「Update」
• 読み込んだ PSD の書き出しは失敗することがある。元のファイルは残す

参考：ag-psd公式READMEと、31.0.2での実行結果（2026年9月29日）。2026年10月24日にREADMEとコードを再照合し、非対応の色モードと掲載例の制約を補足しました。今回、Node.jsやPhotoshopでの再実行はしていません。npmの導入例は版を固定していないため、当時の環境の再現には版指定が必要です。2026年10月29日にnpmの最新配布33.0.0と公式リポジトリのコミットc82ba4e44d00d9ad48236ec183c7e3a1a5c7fd04が一致することを確認し、対応形式の説明を更新しました。33.0.0で掲載コードやPhotoshop表示を再検証した結果ではありません。

よくある質問：ag-psdでPSDを読み書きする

ag-psdとは、何ですか？

JavaScript（Node.jsとブラウザー）でPSDを読み書きできる、MITライセンスのライブラリです。Photoshopが無くても、レイヤーの一覧を取り出したり、レイヤーを組んだPSDを作ったり、文字レイヤーの文字を書き換えたりできます。

どうやって入れて、使いますか？

入れ方は npm i ag-psd canvas です（Node.jsで画像を扱うには、canvasも要ります）。Node.jsでは、require(‘ag-psd/initialize-canvas’)で、画像を扱う準備をしてから使います。読むときはreadPsd(バッファ)、書くときはwritePsdBuffer(オブジェクト)です。

レイヤーの一覧だけを読みたいときは？

skipLayerImageData: trueはレイヤーの画像データを省略する指定です。合成画像も省略したい場合はskipCompositeImageData: trueも指定します。掲載例では合成画像は読み込むため、画像データを一切読まない例ではありません。記事のテストでは、文字レイヤーはl.text.textで文字を、調整レイヤーはl.adjustment.typeで種類を取り出せました。

文字レイヤーの文字を書き換えるときの注意点は？

書き換えたら、invalidateTextLayers: true を付けて書き出します。READMEによると、ag-psdは文字レイヤーの画像を描き直さないので、Photoshopで開くと更新を求める画面が出ます。そこで「Update」を選ぶと、Photoshopが文字を描き直します（「No」を選ぶと文字レイヤーが壊れた状態で残る）。

書き出しでエラーが出たときは、どうすればよいですか？

テスト用のtext.psdをそのまま書き出すとエラーで止まりました。止まったのは、レイヤーではなく、PSD全体の付加情報（image resources）を書くところでした。psd.imageResourcesを消してから書き出すと、書き出せて、ag-psdとpsd-toolsの両方で、書き換えた文字を読めました。ただし、付加情報には解像度などの設定も入っているので、消すと失われるものがあります。読み込んで書き出す使い方は、PSDによっては失敗するので、元のファイルは必ず残しておきます。

ag-psdでできないことは、何ですか？

33.0.0ではCMYK・インデックスカラーや16/32bitの読み込みに対応しますが、書き出しはRGB・8bitです。CMYKの変換はSWOP v2の近似で埋め込みICCは使わないため、色の一致を前提にしないでください。Lab・マルチチャンネル・ダブルトーンの読み込みは非対応です。PSBには対応し、書き出しにはpsb: trueを指定します。文字レイヤーは実装が途中で、縦書きの書き出しは壊れることがあり、定義済みの段落スタイル・文字スタイルの読み書きは非対応です。個別の文字装飾や段落属性がすべて非対応という意味ではありません。描画オプション・ベクター・文字を変えても、画像の描き直しはしません。Photoshopの多くのファイルが使う圧縮のパターンは非対応です。利用者が送ってきたPSDを扱うときは、大きさやビット数を先に確かめるよう、READMEに書かれています。

Pythonのpsd-toolsとは、どう使い分けますか？

ag-psdはJavaScript（Node.js・ブラウザー）、psd-toolsはPythonです。どちらも読めます。新しく作るのはag-psdが得意（レイヤーを組める）で、psd-toolsは基本的な編集のみです。見た目の合成は、ag-psdはしない（自分で行う）のに対し、psd-toolsは一部の調整レイヤー・効果まで対応します。記事では、ag-psdで作ったPSD（グループと、不透明度50%の四角を含む）を、psd-toolsでも読み込めることを確かめています。

記事は、どの環境で確認したものですか？ 最新はどこで確認しますか？

2026年9月29日にWindows 11で、ag-psd 31.0.2、canvas 3.2.3、Node.js 24.15.0を使って試した結果です。読み込みの確認には、psd-toolsの公式リポジトリにあるテスト用のPSD（MIT）を使いました。ライブラリは更新されるため、最新はag-psdのREADMEで確認してください。