n8n

n8n ワークフロー自動化スキル

目的

n8n 自動化プラットフォームでのワークフロー、カスタムノード、インテグレーションの開発を専門的に支援します。AI アシスタントがワークフローを設計し、カスタムコードノードを記述し、TypeScript ベースのカスタムノードを構築し、外部サービスを統合し、AI エージェントのパターンを実装できるようにします。

このスキルを使用するタイミング

次の場合にこのスキルを使用してください。

• 複数のサービスを組み合わせた自動化ワークフローを設計するとき
• ワークフローノード内で JavaScript／Python コードを記述するとき
• TypeScript でカスタムノードを構築するとき
• API、データベース、クラウドサービスを統合するとき
• LangChain を使った AI エージェントのワークフローを作成するとき
• ワークフローの実行エラーをトラブルシューティングするとき
• セルフホスト可能な n8n のデプロイを計画するとき
• 手作業のプロセスを自動化されたワークフローに変換するとき

次の場合はこのスキルを使用しないでください。

• 一般的な自動化に関するアドバイス（適切な言語／プラットフォームのスキルを使用してください）
• クラウドプラットフォーム固有のインテグレーション（クラウドプロバイダーのスキルと併用してください）
• データベース設計（データベース専門スキルを使用してください）
• フロントエンド開発（n8n の UI カスタマイズは最小限です）

n8n の主要な概念

プラットフォームのアーキテクチャ

実行環境：

• Node.js ベースの実行エンジン
• TypeScript（90.7%）と Vue.js フロントエンド
• pnpm モノレポ構成
• セルフホストまたはクラウドへのデプロイに対応

ワークフロー実行モデル：

1. 手動トリガー - ユーザーが開始する実行
2. Webhook トリガー - HTTP エンドポイントによる起動
3. スケジュールトリガー - Cron に基づく実行タイミング
4. イベントトリガー - 外部サービスのイベント（データベースの変更、ファイルのアップロード）
5. エラートリガー - ワークフローの失敗への対応

Fair-code ライセンス：

• Apache 2.0 と Commons Clause
• セルフホストおよび無制限の実行は無料
• SaaS の提供には商用利用の制限あり

ノードの種類とカテゴリ

コアノード（データ操作）：

• Code - JavaScript／Python を実行
• Set - 変数の値を割り当て
• If - 条件分岐
• Switch - 複数分岐のルーティング
• Merge - データストリームを結合
• Split In Batches - 大規模なデータセットを段階的に処理
• Loop Over Items - データを反復処理

トリガーノード（ワークフローの開始）：

• Webhook - HTTP エンドポイント
• Schedule - 時間ベースの実行
• Manual Trigger - ユーザーによる起動
• Error Trigger - ワークフローの失敗を捕捉
• Start - デフォルトの開始点

アクションノード（500 以上のインテグレーション）：

• API コネクター（REST、GraphQL、SOAP）
• データベースクライアント（PostgreSQL、MongoDB、MySQL、Redis）
• クラウドサービス（AWS、GCP、Azure、Cloudflare）
• コミュニケーション（メール、Slack、Discord、SMS）
• ファイル操作（FTP、S3、Google Drive、Dropbox）
• 認証（OAuth2、API キー、JWT）

AI ノード（LangChain とのインテグレーション）：

• AI Agent - 自律的な意思決定
• AI Chain - LLM の逐次処理
• AI Transform - LLM によるデータ操作
• Vector Store - 埋め込みの保存と取得
• Document Loaders - ファイルからテキストを抽出

データフローと接続

接続の種類：

1. メイン接続 - 主なデータフロー（実線）
2. エラー接続 - エラー時のルーティング（赤い破線）

データ構造：

// Input/output format for all nodes
[
  {
    json: { /* Your data object */ },
    binary: { /* Optional binary data (files, images) */ },
    pairedItem: { /* Reference to source item */ }
  }
]

データへのアクセス方法：

• 式 - {{ $json.field }}（現在のノードの出力）
• 入力参照 - {{ $('NodeName').item.json.field }}（特定のノード）
• すべてのアイテム - {{ $input.all() }}（データセット全体）
• 最初のアイテム - {{ $input.first() }}（単一のアイテム）
• アイテムインデックス - {{ $itemIndex }}（現在の反復処理）

認証情報と認証

認証情報の種類：

• 定義済み - 人気のサービス向けに事前設定（OAuth2、API キー）
• 汎用 - HTTP 認証（Basic、Digest、Header Auth）
• カスタム - ユーザー定義の認証情報構成

セキュリティの実践：

• 認証情報は暗号化されてデータベースに保存されます
• 機密情報に環境変数を使用できます
• ワークフロー間で認証情報を共有できます（任意）
• ローテーション：手動での更新が必要です

ワークフロー設計の方法論

計画フェーズ

ステップ 1：要件を定義する

• 入力ソース（Webhook、スケジュール、データベース）
• 必要なデータ変換
• 出力先（API、ファイル、データベース）
• エラー処理の要件
• 実行頻度とデータ量

ステップ 2：データフローをマッピングする

• トリガーイベントを特定する
• 変換ステップを列挙する
• 検証ルールを指定する
• 分岐ロジックを定義する
• エラー復旧を計画する

ステップ 3：ノードを選択する

選択基準：

• 利用可能な場合はネイティブノードを使用します（最適化され、保守されています）
• 50 行未満のカスタムロジックにはCode nodeを使用します
• 100 行を超える再利用可能な複雑なロジックにはカスタムノードを作成します
• ネイティブノードがない API にはHTTP Request nodeを使用します
• システム操作にはExecute Command nodeを使用します（セキュリティリスクがあります）

実装フェーズ

ワークフロー構造のパターン：

[Trigger] → [Validation] → [Branch (If/Switch)] → [Processing] → [Error Handler]
                                ↓                      ↓
                          [Path A nodes]        [Path B nodes]
                                ↓                      ↓
                          [Merge/Output]         [Output]

モジュール設計：

• 再利用可能なロジックをサブワークフローに切り出します
• モジュール化には Execute Workflow node を使用します
• メインワークフローは 15～20 ノード以内に制限します（可読性のため）
• 入力変数でワークフローをパラメーター化します

エラー処理戦略：

1. Error Trigger ワークフロー - すべての失敗を捕捉します
2. Try/Catch パターン - ノードのエラー出力接続を使用します
3. 再試行ロジック - ノードごとに再試行設定を構成します
4. 検証ノード - データチェックには If/Switch を使用します
5. 通知 - 重大な失敗を通知します（Email、Slack）

テストフェーズ

ローカルテスト：

• サンプルデータで実行します
• 各ノードの出力を検証します（データパネルを確認）
• 無効なデータでエラーパスをテストします
• 認証情報の接続を確認します

本番環境での検証：

• ワークフローを有効にし、実行を監視します
• 実行履歴で失敗がないか確認します
• リソース使用量を確認します（実行時間、メモリ）
• 出力データの品質を検証します

ワークフローでのコード実行

Code Node（JavaScript）

利用可能な API：

• Node.js の組み込みモジュール - fs、path、crypto、https
• Lodash - _.groupBy()、_.sortBy() など
• Luxon - DateTime の操作
• n8n ヘルパー - $input、$json、$binary

基本構造：

// Access input items
const items = $input.all();

// Process data
const processedItems = items.map(item => {
  const inputData = item.json;

  return {
    json: {
      // Output fields
      processed: inputData.field.toUpperCase(),
      timestamp: new Date().toISOString()
    }
  };
});

// Return transformed items
return processedItems;

データ変換パターン：

フィルタリング：

const items = $input.all();
return items.filter(item => item.json.status === 'active');

集約：

const items = $input.all();
const grouped = _.groupBy(items, item => item.json.category);

return [{
  json: {
    summary: Object.keys(grouped).map(category => ({
      category,
      count: grouped[category].length
    }))
  }
}];

API 呼び出し（非同期）：

const items = $input.all();
const results = [];

for (const item of items) {
  const response = await fetch(`https://api.example.com/data/${item.json.id}`);
  const data = await response.json();

  results.push({
    json: {
      original: item.json,
      enriched: data
    }
  });
}

return results;

コード内のエラー処理：

const items = $input.all();

return items.map(item => {
  try {
    // Risky operation
    const result = JSON.parse(item.json.data);
    return { json: { parsed: result } };
  } catch (error) {
    return {
      json: {
        error: error.message,
        original: item.json.data
      }
    };
  }
});

Code Node（Python）

利用可能なライブラリ：

• 標準ライブラリ - json、datetime、re、requests
• NumPy - 配列操作
• Pandas - データ分析（インストールされている場合）

基本構造：

# Access input items
items = _input.all()

# Process data
processed_items = []
for item in items:
    input_data = item['json']

    processed_items.append({
        'json': {
            'processed': input_data['field'].upper(),
            'timestamp': datetime.now().isoformat()
        }
    })

# Return transformed items
return processed_items

複雑さの評価：コードノード

• シンプルな変換（map/filter）：1
• エラー処理を伴う API 呼び出し：2
• 複数ステップの非同期操作：3
• ライブラリを使用する複雑なアルゴリズム：4
• パフォーマンスが重要な処理：5（カスタムノードを検討してください）

カスタムノードの開発

カスタムノードを作成する場合

次の場合はカスタムノードを作成します：

• 複数のワークフローで再利用するロジック（3 件超）
• 複雑な認証要件
• パフォーマンスが重要な操作（Code node のオーバーヘッド）
• コミュニティへの貢献（公開 npm パッケージ）
• 組織固有の統合

次の場合は Code node を使用します：

• 一度限りの変換
• 迅速なプロトタイピング
• シンプルな API 呼び出し（100 行未満）

開発スタイル

[コード例を参照：examples/n8n_custom_node.ts]

1. プログラム形式（完全な制御）

用途：

• 複雑な認証フロー
• 高度なパラメーター検証
• カスタム UI コンポーネント
• 状態管理を伴うポーリング操作

[参照：examples/n8n_custom_node.ts の CustomNode クラス]

2. 宣言形式（簡素化）

用途：

• 標準的な CRUD 操作
• RESTful API ラッパー
• 複雑なロジックを伴わないシンプルな統合

[参照：examples/n8n_custom_node.ts の operations および router エクスポート]

追加の例：

• 認証情報の設定：examples/n8n_custom_node.ts の customApiCredentials
• 認証情報の検証：examples/n8n_custom_node.ts の validateCredentials()
• ポーリングトリガー：examples/n8n_custom_node.ts の PollingTrigger クラス

開発ワークフロー

ステップ 1：Node を初期化する

# Create from template
npm create @n8n/node my-custom-node

# Directory structure created:
# ├── nodes/
# │   └── MyCustomNode/
# │       └── MyCustomNode.node.ts
# ├── credentials/
# │   └── MyCustomNodeApi.credentials.ts
# └── package.json

ステップ 2：ロジックを実装する

• Node のプロパティを定義する（パラメーター、認証情報）
• execute メソッドを実装する
• エラー処理を追加する
• 単体テストを書く（任意）

ステップ 3：ビルドしてテストする

# Build TypeScript
npm run build

# Link locally for testing
npm link

# In n8n development environment
cd ~/.n8n/nodes
npm link my-custom-node

# Restart n8n to load node
n8n start

ステップ 4：公開する

# Community node (npm package)
npm publish

# Install in n8n
Settings → Community Nodes → Install → Enter package name

複雑さの評価：カスタム Node

• 宣言型 CRUD ラッパー：2
• 認証を伴うプログラム型：3
• 複雑な状態管理：4
• 高度なポーリング／Webhook：5

統合パターン

API 統合戦略

判断ツリー：

Has native node? ──Yes──> Use native node
     │
     No
     ├──> Simple REST API? ──Yes──> HTTP Request node
     ├──> Complex auth (OAuth2)? ──Yes──> Build custom node
     ├──> Reusable across workflows? ──Yes──> Build custom node
     └──> One-off integration? ──Yes──> Code node with fetch()

HTTP Request Node のパターン

クエリパラメーターを使った GET：

URL: https://api.example.com/users
Method: GET
Query Parameters:
  - status: active
  - limit: 100
Authentication: Header Auth
  - Name: Authorization
  - Value: Bearer {{$credentials.apiKey}}

JSON ボディを使った POST：

URL: https://api.example.com/users
Method: POST
Body Content Type: JSON
Body:
{
  "name": "={{ $json.name }}",
  "email": "={{ $json.email }}"
}

ページネーション処理（Code Node）：

let allResults = [];
let page = 1;
let hasMore = true;

while (hasMore) {
  const response = await this.helpers.request({
    method: 'GET',
    url: `https://api.example.com/data?page=${page}`,
    json: true,
  });

  allResults = allResults.concat(response.results);
  hasMore = response.hasNext;
  page++;
}

return allResults.map(item => ({ json: item }));

Webhook パターン

Webhook の受信：

1. Webhook トリガー Node を作成する
2. HTTP メソッドを設定する（POST/GET）
3. 認証を設定する（なし／Header Auth／Basic Auth）
4. Node から Webhook URL を取得する
5. 外部サービスに URL を登録する

Webhook への応答：

// In Code node after webhook trigger
const webhookData = $input.first().json;

// Process data
const result = processData(webhookData);

// Return response (synchronous webhook)
return [{
  json: {
    status: 'success',
    data: result
  }
}];

Webhook URL の構造：

Production: https://your-domain.com/webhook/workflow-id
Test: https://your-domain.com/webhook-test/workflow-id

データベース統合

一般的なパターン：

パラメーターを使ったクエリ：

-- PostgreSQL node
SELECT * FROM users
WHERE created_at > $1
  AND status = $2
ORDER BY created_at DESC

-- Parameters from previous node
Parameters: ['{{ $json.startDate }}', 'active']

一括挿入：

// Code node preparing data for database
const items = $input.all();
const values = items.map(item => ({
  name: item.json.name,
  email: item.json.email,
  created_at: new Date().toISOString()
}));

return [{ json: { values } }];

// Next node: PostgreSQL
// INSERT INTO users (name, email, created_at)
// VALUES {{ $json.values }}

ファイル操作

S3 へのアップロード：

Workflow: File Trigger → S3 Upload
- File Trigger: Monitor directory for new files
- S3 node:
  - Operation: Upload
  - Bucket: my-bucket
  - File Name: {{ $json.fileName }}
  - Binary Data: true (from file trigger)

ダウンロードと処理：

HTTP Request (download) → Code (process) → Google Drive (upload)
- HTTP Request: Binary response enabled
- Code: Process $binary.data
- Google Drive: Upload with binary data

AI エージェントのワークフロー

LangChain 統合

AI エージェント Node の設定：

• エージェントタイプ：OpenAI Functions、ReAct、Conversational
• LLM：OpenAI、Anthropic、Hugging Face、Ollama（ローカル）
• メモリ：Buffer、Buffer Window、Summary
• ツール：Calculator、Webhook、データベースクエリ、カスタム API 呼び出し

基本的なエージェントパターン：

Manual Trigger → AI Agent → Output
- AI Agent:
  - Prompt: "You are a helpful assistant that {{$json.task}}"
  - Tools: [Calculator, HTTP Request]
  - Memory: Conversation Buffer Window

ゲートキーパーパターン（監視付き AI）

ユースケース： エージェントのアクション前に人間が承認する

Webhook → AI Agent → If (requires approval) → Send Email → Wait for Webhook → Execute Action
                            ↓ (auto-approve)
                        Execute Action

実装：

1. AI エージェントがアクションプランを生成する
2. If Node が信頼度スコアを確認する
3. 信頼度が低い場合 → 承認リクエストのメールを送信する
4. Webhook を待機する（承認／拒否）
5. 応答に基づいて実行または中止する

反復型エージェントパターン

ユースケース： 状態を保持した複数ステップの問題解決

Loop Start → AI Agent → Tool Execution → State Update → Loop End (condition check)
     ↑______________________________________________________________|

状態管理：

// Code node - Initialize state
return [{
  json: {
    task: 'Research topic',
    iteration: 0,
    maxIterations: 5,
    context: [],
    completed: false
  }
}];

// Code node - Update state
const state = $json;
state.iteration++;
state.context.push($('AI Agent').item.json.response);
state.completed = state.iteration >= state.maxIterations || checkGoalMet(state);

return [{ json: state }];

RAG（検索拡張生成）パターン

Query Input → Vector Store Search → Format Context → LLM → Response Output

ベクトルストアの設定：

1. Document Loader Node → テキストをチャンクに分割する
2. Embeddings Node → ベクトルを生成する（OpenAI、Cohere）
3. Vector Store Node → Pinecone/Qdrant/Supabase に保存する
4. クエリ：関連するチャンクを取得する → LLM のプロンプトに挿入する

複雑さの評価：AI ワークフロー

• シンプルな LLM 呼び出し：1
• ツールを備えたエージェント：3
• ゲートキーパーパターン：4
• マルチエージェントのオーケストレーション：5

デプロイとホスティング

セルフホストのオプション

[コード例を参照：examples/n8n_deployment.yaml]

Docker（推奨）：

• PostgreSQL を使用する Docker Compose
• スケーリングに向けたキューモードの設定
• ボリュームに応じたリソース要件

[参照：examples/n8n_deployment.yaml の docker-compose 設定]

npm（開発用）：

npm install n8n -g
n8n start
# Access: http://localhost:5678

環境設定：

[参照：examples/n8n_deployment.yaml の環境変数の完全なリファレンス]

必須の変数：

• N8N_HOST - Webhook 用の公開 URL
• WEBHOOK_URL - Webhook エンドポイントのベース URL
• N8N_ENCRYPTION_KEY - 認証情報の暗号化用（保持が必要）
• DB_TYPE - データベース（SQLite/PostgreSQL/MySQL/MariaDB）
• EXECUTIONS_DATA_SAVE_ON_ERROR - エラーログ
• EXECUTIONS_DATA_SAVE_ON_SUCCESS - 成功ログ

パフォーマンス調整用の変数は examples/n8n_deployment.yaml に記載されています

スケーリングに関する考慮事項

キューモード（高負荷時）：

# Separate main and worker processes
# Main process (UI + queue management)
N8N_QUEUE_MODE=main n8n start

# Worker processes (execution only)
N8N_QUEUE_MODE=worker n8n worker

データベース：

• SQLite：開発／低負荷（1日あたりの実行数が1000未満）
• PostgreSQL：本番環境（推奨）
• MySQL/MariaDB：既存のインフラ向けの代替手段

リソース要件：

ワークフローの負荷	CPU	RAM	データベース
1日あたりの実行数が100未満	1コア	512MB	SQLite
1日あたり100～1000回	2コア	2GB	PostgreSQL
1日あたり1000～10000回	4コア	4GB	PostgreSQL
1日あたり10000回超	8コア以上	8GB以上	PostgreSQL + キューモード

モニタリング：

• 実行ログを有効にします（EXECUTIONS_DATA_SAVE_*）
• エラーワークフローを設定します（Error Trigger ノード）
• データベースのサイズを監視します（実行履歴のクリーンアップ）
• Webhook の応答時間を追跡します

ベストプラクティス

ワークフローの設計

1. モジュール性：

• 再利用可能なロジックを Execute Workflow ノードに切り出します
• ワークフローの責任を単一に限定します
• 共通の操作（検証、フォーマット）にはサブワークフローを使用します

2. エラー耐性：

• 重要なノードにエラー出力を追加します
• 再試行ロジックを実装します（ノード設定）
• アラート用の Error Trigger ワークフローを作成します
• エラーを外部システム（Sentry、CloudWatch）に記録します

3. パフォーマンス：

• 大規模なデータセット（1000件超）には Split In Batches を使用します
• ループ内の HTTP リクエストを最小限に抑えます（API 呼び出しをバッチ処理）
• 高頻度のワークフローでは実行ログを無効にします
• コストの高い処理を変数にキャッシュします

4. セキュリティ：

• シークレットは認証情報に保存します（ハードコードしないでください）
• 設定には環境変数を使用します
• Webhook 認証を有効にします
• Execute Command ノードの使用を制限します（またはグローバルに無効にします）
• コードノードにインジェクションの脆弱性がないか確認します

5. 保守性：

• 複雑なワークフローにメモを追加します（Sticky Note ノード）
• 一貫した命名規則を使用します（動詞 + 名詞：「ユーザーを取得」、「データを変換」）
• ワークフローの設定に目的を記載します
• ワークフローをバージョン管理します（JSON をエクスポートし、Git にコミット）

ノード内のコード品質

1. データの検証：

// Always validate input structure
const items = $input.all();

for (const item of items) {
  if (!item.json.email || !item.json.name) {
    throw new Error(`Invalid input: missing required fields at item ${item.json.id}`);
  }
}

2. エラーコンテキスト：

// Provide debugging information
try {
  const result = await apiCall(item.json.id);
} catch (error) {
  throw new Error(`API call failed for ID ${item.json.id}: ${error.message}`);
}

3. 冪等性：

// Check existence before creation
const exists = await checkExists(item.json.uniqueId);
if (!exists) {
  await createRecord(item.json);
}

ワークフローパターンライブラリ

パターン 1：API 同期

用途： 2つのシステム間でデータを同期します

Schedule Trigger (hourly) → Fetch Source Data → Transform → If (record exists) → Update Target
                                                                    ↓ (new)
                                                                Create in Target

複雑さ： 2

パターン 2：エラー復旧

用途： 指数バックオフを使用して失敗した操作を再試行します

Main Workflow → Process → Error → Error Trigger Workflow
                                        ↓
                                   Wait (delay) → Retry → If (max retries) → Alert

複雑さ： 3

パターン 3：データ拡充

用途： 外部ソースのデータでデータを拡充します

Webhook → Split In Batches → For Each Item:
                                  ↓
                             API Call (enrich) → Code (merge) → Batch Results
                                                                      ↓
                                                                Database Insert

複雑さ： 3

パターン 4：イベント駆動型処理

用途： メッセージキューからイベントを処理します

SQS Trigger → Parse Message → Switch (event type) → [Handler A, Handler B, Handler C] → Confirm/Delete Message

複雑さ： 3

パターン 5：人間が介在するプロセス

用途： 承認ワークフロー

Trigger → Generate Request → Send Email (approval link) → Webhook (approval response) → If (approved) → Execute Action
                                                                                              ↓ (rejected)
                                                                                         Send Rejection Notice

複雑さ： 4

パターン 6：多段階 ETL

用途： 複雑なデータパイプライン

Schedule → Extract (API) → Validate → Transform → Load (Database) → Success Notification
                               ↓                                            ↓
                          Error Handler ────────────────────> Error Notification

複雑さ： 3

品質ゲート

完了の定義：ワークフロー

次の条件を満たすと、ワークフローは本番環境で使用できる状態です。

1. 機能：

   • ✓ テストデータですべてのノードがエラーなく実行される
   • ✓ 無効な入力を使ってエラーパスをテスト済み
   • ✓ 出力形式が要件に照らして検証済み

2. エラー処理：

   • ✓ 重要なノードでエラー出力が設定されている
   • ✓ アラート用の Error Trigger ワークフローが作成されている
   • ✓ 該当する箇所に再試行ロジックが設定されている

3. セキュリティ：

   • ✓ 認証情報を使用している（シークレットをハードコードしていない）
   • ✓ Webhook 認証が有効になっている
   • ✓ 入力検証が実装されている

4. ドキュメント：

   • ✓ 設定にワークフローの説明が記入されている
   • ✓ 複雑なロジックがメモで文書化されている
   • ✓ パラメーターの説明が明確である

5. パフォーマンス：

   • ✓ 現実的なデータ量でテスト済み
   • ✓ 実行時間が許容範囲内である
   • ✓ リソース使用量が上限内である

完了の定義：カスタムノード

カスタムノードは、次の条件を満たすと本番環境で使用できる状態です。

1. 機能：

   • ✓ すべての操作が実装され、テストされている
   • ✓ 認証情報との連携が機能している
   • ✓ パラメーターが検証されている

2. コード品質：

   • ✓ TypeScript の型が定義されている
   • ✓ エラー処理が十分に実装されている
   • ✓ ハードコードされた値がない（パラメーターを使用する）

3. ドキュメント：

   • ✓ インストール手順を記載した README
   • ✓ パラメーターの説明が明確
   • ✓ ワークフローの例が用意されている

4. 配布：

   • ✓ npm に公開されている（公開する場合）
   • ✓ 適切にバージョン管理されている
   • ✓ 依存関係が package.json に宣言されている

エラー処理ガイド

よくある問題と解決方法

問題：「Invalid JSON」でワークフローが失敗する

• 原因： ノードの出力形式が正しくない
• 解決方法：

  // Ensure return format
  return [{ json: { your: 'data' } }];
  // NOT: return { your: 'data' };
  

問題：「Cannot read property of undefined」

• 原因： 前のノードからデータが渡されていない
• 解決方法：

  // Check existence before access
  const value = $json.field?.subfield ?? 'default';
  

問題：Webhook がデータを受信しない

• 原因： Webhook URL または認証が正しくない
• 解決方法：
  • URL が外部サービスの設定と一致していることを確認する
  • 認証方式が一致していることを確認する（None／Header／Basic）
  • curl でテストする：

    curl -X POST https://your-n8n.com/webhook/test \
      -H "Content-Type: application/json" \
      -d '{"test": "data"}'
    

問題：カスタムノードが表示されない

• 原因： 正しくリンクまたはインストールされていない
• 解決方法：

  # Check installation
  npm list -g | grep n8n-nodes-
  
  # Reinstall if needed
  npm install -g n8n-nodes-your-node
  
  # Restart n8n
  

問題：メモリ使用量が多い

• 原因： 大量のデータセットをバッチ処理せずに処理している
• 解決方法：
  • Split In Batches ノードを使用する（バッチサイズ：100～1000）
  • 実行頻度の高いワークフローでは、実行データの保存を無効にする
  • EXECUTIONS_DATA_PRUNE=true を設定する

問題：認証情報が機能しない

• 原因： 認証情報の設定が正しくない、またはトークンの有効期限が切れている
• 解決方法：
  • OAuth2 認証情報を再認証する
  • API キー／トークンが有効であることを確認する
  • サービスでの認証情報の権限を確認する

デバッグ方法

1. ノードの出力を確認する：

• ノードをクリック → 実行データを表示する
• json タブと binary タブを確認する
• データ構造が想定どおりであることを確認する

2. デバッグ用 Code ノードを追加する：

// Log intermediate values
const data = $json;
console.log('Debug data:', JSON.stringify(data, null, 2));
return [{ json: data }];

3. 検証に If ノードを使用する：

// Expression to check data quality
{{ $json.email && $json.email.includes('@') }}

4. 実行ログを有効にする：

• Settings → Log → レベルを debug に設定する
• Docker のログを確認する：docker logs n8n -f

5. 個別にテストする：

• Manual Trigger を使ってテスト用ワークフローを作成する
• 問題のあるノードをコピーする
• 静的なテストデータを使用する

参考資料

公式ドキュメント

• メインドキュメント： https://docs.n8n.io
• ノードリファレンス： https://docs.n8n.io/integrations/builtin/
• カスタムノード開発： https://docs.n8n.io/integrations/creating-nodes/
• 式のリファレンス： https://docs.n8n.io/code/expressions/

コードリポジトリ

• コアプラットフォーム： https://github.com/n8n-io/n8n
• ドキュメント： https://github.com/n8n-io/n8n-docs
• コミュニティノード： https://www.npmjs.com/search?q=n8n-nodes

コミュニティリソース

• フォーラム： https://community.n8n.io
• テンプレート： https://n8n.io/workflows（ワークフローライブラリ）
• YouTube： n8n 公式チャンネル（チュートリアル）

関連スキル

• クラウド連携については、cloud-devops-expert スキルを使用します
• データベース設計については、database-specialist スキルを使用します
• API 設計については、api-design-architect スキルを使用します
• TypeScript 開発については、言語固有のスキルを使用します

---

バージョン： 1.0.0 最終更新日： 2025-11-13 複雑さの評価： 3（中程度 — プラットフォーム固有の知識が必要） 習得に必要な時間の目安： 習熟まで 8～12 時間