kintoneカスタマイズJavaScriptが動かない時のデバッグ手順：CSPエラー／ライブラリ読込順／APIトークン権限の見極め方
目次 クリックで開く
kintoneのJavaScriptカスタマイズが「ローカルでは動くのにkintone上で動かない」とき、原因の大半は「CSP（Content Security Policy）違反」「ライブラリ読込順」「APIトークンの権限不足」の3つに集約されます。本記事では、Chrome DevToolsを使った最短診断手順と、各原因の解決パターンを実例コード付きで解説します。
最短診断：原因の見極めチェックリスト
| 原因カテゴリ | 確認ポイント |
|---|---|
| CSP違反 | 外部CDNから読み込んだスクリプトがCSPでブロック。kintoneのCSP設定でドメイン許可が必要。 |
| ライブラリ読込順 | jQuery, lodash等の依存ライブラリがメインスクリプトより後に読み込まれている。 |
| APIトークン権限 | アプリ設定→APIトークンで「レコード閲覧」「レコード追加」等の権限が不足。 |
| kintone JS API バージョン | kintone.app.record.get()が古いバージョンで未定義。最新APIリファレンス確認。 |
| CORS問題 | 外部API呼び出しでCORSエラー。kintoneプロキシAPI（kintone.proxy）の利用が必要。 |
kintone JSカスタマイズ エラー種別 × 根本原因 × 解決ステップ 早見表
前のセクションで原因カテゴリの診断チェックリストを整理しましたが、実際に発生するエラーは「コンソールに表示されるメッセージ」から逆引きするのが最速です。以下の表は、kintone JSカスタマイズで頻出するエラーメッセージ・現象ごとの根本原因と解決ステップをまとめたものです。
| エラーメッセージ / 現象 | 根本原因 | 解決ステップ | 再発防止策 |
|---|---|---|---|
| Refused to load the script … because it violates the following Content Security Policy directive | 外部CDN（jQuery, Chart.jsなど）のURLがkintoneのCSP許可リストに未登録 | ①kintone管理コンソール→システム管理→JavaScriptカスタマイズ設定でCSP許可ドメインに外部CDNのドメインを追加。②または外部ライブラリをkintoneに直接アップロードしてCDN参照をやめる | 外部CDNのURLは将来的に変更されることがある。可能な限りライブラリファイルをkintoneに直接アップロードする方針を取り、CDN依存を最小化する |
| kintone is not defined（またはkintone.events is not a function） | kintone.jsの読み込みより前にカスタマイズJSが実行されている。または本番環境以外（ローカルhtmlファイル等）でテストしている | ①JSファイルの読み込み順をkintone管理画面で確認し、kintone本体より後に実行されるよう並び順を変更。②ローカルテスト中の場合はkintone開発環境（kintone UI Component等）を使用する | kintoneのAPIを使うコードは必ずkintone.events.onのコールバック内に記述する。イベントの外でkintone APIを参照するコードを書かない |
| カスタマイズが特定のレコード/画面だけ動かない | kintoneのイベントタイプの指定が不足（例：詳細画面のみ対応でモバイル画面イベントが未設定）。または条件分岐のロジックが特定ケースで機能していない | ①ChromeのDevToolsコンソールで対象画面を開き、エラーや予期しない値をログ確認。②kintone.events.onの第1引数に必要なイベントタイプが全て含まれているか確認（’app.record.detail.show’と’mobile.app.record.detail.show’の両方が必要なケース等） | カスタマイズ開発時にデスクトップ・モバイル・作成・詳細・編集の全イベントタイプを対象に動作確認する検証チェックリストを作成して運用する |
| 他のカスタマイズと干渉して予期しない動作が起きる | 複数のJSファイルが同じフィールドや同じイベントに対して競合する処理を実行している。またはグローバル変数の名前が衝突している | ①全JSファイルの処理内容をドキュメント化して依存関係を把握。②各JSをIIFE（即時実行関数式）でラップしてグローバルスコープへの影響を遮断。③kintone管理画面でJSの読み込み順を変更して影響を確認 | kintoneカスタマイズの全JSファイルを一元管理するドキュメント（担当者・対象アプリ・処理概要・最終更新日）を整備する。退職者が作成したカスタマイズが「ブラックボックス」になる前に棚卸しを行う |
| APIリクエストが失敗する（kintone REST API） | APIトークンの権限不足、リクエストのフォーマットエラー（フィールドコードの誤り、JSONの構造ミス）、またはレート制限超過 | ①DevToolsのNetworkタブでAPIリクエストのレスポンス詳細（HTTPステータスコード・エラーメッセージ）を確認。②kintone APIのエラーコード一覧でエラーの原因を特定。③APIトークンに必要な権限（レコード参照/追加/編集/削除）が付与されているか確認 | APIトークンは用途ごとに最小権限で発行する。「全権限付きトークンを使い回す」設計は権限漏洩リスクが高い。トークンはハードコードせず環境変数または設定アプリのフィールドから取得する |
この表で最も多いのが「CSP違反によるスクリプトブロック」です。kintoneは2023年以降にCSPを段階的に強化しており、以前は動いていたCDN参照のカスタマイズが突然動かなくなるケースが増えています。外部CDNを使っているカスタマイズがある場合は、ライブラリをkintoneに直接アップロードする形式への移行を優先することが、長期的な保守コストを下げる最善策です。
解決手順（推奨実行順）
- Chrome DevToolsの Console タブで赤いエラーメッセージを確認。
- 「Refused to load… CSP」が出ていれば、kintoneシステム管理→セキュリティでドメイン許可を追加。
- 「is not a function」「undefined」が出ていれば、kintone(()=>{…}) の依存ライブラリ配列順序を確認。
- APIエラー（403）→ アプリ設定のAPIトークン or ユーザーアクセス権限を確認。
- CORSエラー（外部API）→ kintone.proxy() に書き換え、URL／メソッド／ヘッダ／ボディの4要素を渡す。
- 本番反映前に必ず「テストアプリ」でフィールドコードと実装が一致するか確認。
kintoneのJavaScriptカスタマイズやAPIトークン管理にAIコーディング支援を組み込む場合、シークレット分離・トークンの最小スコープ・変更操作への監査証跡の設計をコード実装と同時に整えておくことで、CSPエラーや権限漏れのリスクを本番前に潰せます。kintoneカスタマイズへのAI活用における権限・セキュリティ設計の相談は Claude Code 導入支援 でどうぞ。
よくある質問
kintoneでReactやVueは使える？
使えます。webpack等でバンドル → kintone-cli または手動でJSを上げます。ただしCSP設定の調整が必要なことが多いです。
無料プラグインで実現できる範囲は？
サブテーブル集計・条件分岐・PDF出力など多くは無料プラグインで足ります。独自業務ロジックはJSカスタマイズが必須です。
kintone-CLI（旧 customize-uploader）は使うべき？
5人以上の開発体制ならGit管理 + CLIアップロードが標準。1人開発ならブラウザ直接アップロードで十分です。
kintoneプロキシAPIの料金課金は？
kintone APIリクエスト枠（プランごとに月10,000〜100,000回）を消費します。大量リクエストは注意。
セキュリティを保ちつつ外部公開する方法は？
kintone API + ゲストスペース or REST APIラッパーをCloud Run/Lambdaで構築 → 認証層を別建てするのが現実解です。
まとめ
kintoneのJavaScriptカスタマイズで本番だけ動かない場合、最初に直すべきなのはコード量ではなく、原因の切り分け手順です。
ConsoleのエラーをCSP、読込順、権限、CORSに分類してから修正することで、テストアプリでの検証から本番反映までを安全に進めやすくなります。
kintone業務アプリ・プラグイン活用のご相談
kintoneでの業務アプリ設計や、帳票・連携・自動化を補うプラグインの活用を支援します。現場の運用に合わせたアプリ構成や他システムとの連携まで、具体的な形でご提案します。
CRM・営業支援
Salesforce・HubSpot・kintoneの選定から導入・カスタマイズ・定着まで一貫対応。営業生産性を高め、商談化率を改善します。