Ship SCSS Compiler self-updates
Safe WordPress SCSS compiler with GitHub Release updates
by ship-git-admin · github.com/ship-git-admin/ship-scss-compiler
Install
No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:
wp plugin install https://github.com/ship-git-admin/ship-scss-compiler/archive/refs/heads/main.zipShips its own WordPress updater (Plugin Update Checker), so new versions show up under Dashboard → Updates.
WordPressテーマ内のSCSSエントリーポイントを、同梱のscssphpで安全にCSSへ変換するプラグインです。設定変更なしでは従来どおり、現在の有効テーマの scss/ から直下のエントリーポイントを読み、css/ に同名のCSSを出力します。
安全性と差分コンパイル
_で始まるファイルはpartialとして扱い、単独CSSを出力しません。- 空のエントリーポイントは既存CSSを変更せずスキップします。
- SCSSとpartialの内容ハッシュ、scssphpの
CompilationResult::getIncludedFiles()による依存関係を保存し、関係するCSSだけを再生成します。 - 変更検査は同一リクエスト内で共有し、通常リクエストでは短いスキャンキャッシュを使用します。管理画面の手動実行は必ず再検査します。
- CSSと.mapは同じ出力ディレクトリの一時ファイルを検証してから置換します。コンパイル、検証、権限、置換のいずれかが失敗した場合、公開中のCSSは維持します。
- 同じ入力状態での失敗は初期値300秒（30〜86400秒で設定可能）再試行を抑制します。入力・依存・設定の変更、待ち時間経過、手動実行で再試行できます。
設定
管理画面の「設定 > Ship SCSS Compiler」で変更します。パスは有効テーマを基準にした相対パスで、絶対パス、URL、..、テーマ外のシンボリックリンクは拒否します。
| 設定 | 初期値 | 内容 |
|---|---|---|
| SCSS入力ディレクトリ | scss |
テーマ内の入力ルート |
| CSS出力ディレクトリ | css |
入力の相対サブディレクトリ構造を維持して出力 |
| 対象の選択方法 | 自動検出 | 直下の .scss を対象。_始まりは除外 |
| 明示エントリーポイント | 空 | 入力ディレクトリからの相対パスを1行ずつ指定 |
| サブディレクトリ | 無効 | 自動検出に限り有効化すると再帰的に対象化 |
| CSSデバッグ | 無効 | 有効時だけ展開CSSと外部 .css.map を生成 |
| sourcesContent | 無効 | 有効時だけ元SCSS内容をmapに埋め込む |
| デバッグ解除時の.map削除 | 有効 | このプラグインの所有が確認できるmapだけ削除 |
| CSSキャッシュ更新補助 | 無効 | 管理対象CSSの ver に保存済み内容ハッシュを使用 |
| 失敗の再試行間隔 | 300秒 | 自動再試行抑制の時間 |
設定例
入力が assets/scss/pages/home.scss、出力ディレクトリが assets/css の場合、生成先は assets/css/pages/home.css です。明示指定では次のように記載します。
pages/home.scss
pages/about.scss既存CSSは、設定から対象を外しただけでは削除しません。出力ディレクトリ変更前の生成物も自動削除せず、状態に混在させません。
手動再コンパイル
管理画面の「すべて再コンパイル」または一覧でファイルを選択する「選択したファイルを再コンパイル」を使用します。どちらも manage_options 権限、POST、nonce、サーバー側の再検証、共通ロックを使います。再読み込みによる二重送信を避けるため、実行後は設定画面へリダイレクトします。
一覧では、入力・出力パス、状態、最終成功日時、処理時間、CSS内容ハッシュ、モード、依存数、直近エラー、再試行時刻を確認できます。失敗時は「既存CSSを維持」または「公開可能なCSSがまだありません」と区別して扱います。
CSSキャッシュ更新補助
設定を有効にすると、正常公開済みCSSの保存済みSHA-256を style_loader_src の ver に利用します。毎リクエストに hash_file() を行わず、失敗したコンパイルのハッシュも更新しません。対象は現在の有効テーマの、このプラグインが管理履歴に持つCSSだけで、CDN・外部URL・他プラグイン・WordPress本体のURLは変更しません。ver 以外のクエリとフラグメントは維持します。
テーマ側からは次のヘルパーを明示的に呼べます。
$version = ship_scss_compiler_css_version('css/home.css');
wp_enqueue_style('site-home', get_stylesheet_directory_uri() . '/css/home.css', array(), $version ?: null);引数は有効テーマルートからのCSS相対パス、返り値は正常公開済み内容の64文字SHA-256です。未管理・未生成の場合は空文字です。URLのバージョン更新だけでは、ページキャッシュやCDNに残ったHTML/CSSを消去できないため、必要に応じて各キャッシュも更新してください。
ソースマップとログ
通常モードでは新しいmapを生成せず、CSSにも sourceMappingURL を付けません。デバッグモードでは外部mapがURLから取得される可能性があり、sourcesContent を有効にすると元SCSSの内容・構造も公開され得ます。本番では通常モードを推奨します。この機能は既に配信済みデータや、テーマ内SCSSそのものへの直接アクセスを非公開にはしません。
新しい詳細エラーは公開ディレクトリの平文ログではなく、autoload無効のWordPressオプションに直近100件・30日以内・1件4096文字以内で保存します。管理画面からnonce付きで削除できます。旧バージョンの scss/error_log.log は自動削除せず、存在を警告して管理者が確認後に個別削除できます。所有を確認できないmapも削除せず警告します。
フック
ship_scss_compiler_debug— デバッグ出力の実効値を変更ship_scss_compiler_retry_interval— 再試行抑制秒数を変更ship_scss_compiler_scan_interval— 通常時の入力検査キャッシュ秒数を変更（0で毎回検査）
旧バージョンからの移行
1.2.0以前のデバッグ設定があり、新設定が未保存の場合はデバッグ状態を引き継ぎます。新しい状態はテーマの実体パス、入出力パス、エントリー設定、出力モードを含むコンテキストごとに保存するため、テーマ切り替えや設定変更後に別構成の成功履歴を流用しません。旧CSSと旧mapは勝手に削除せず、所有履歴が作られたものだけを管理します。
GitHub更新
更新チェッカーは従来どおり、公開リポジトリの main ブランチにある最新Releaseだけを確認し、次のRelease Assetが存在する場合だけ更新候補にします。
ship-scss-compiler-x.y.z.zipテスト
WordPress本体に依存しない回帰テストを同梱しています。
php tests/test_core.php入力・出力パス、partial、空ファイル、差分判定、デバッグmap、失敗保護、再試行抑制、明示指定、ネスト出力、選択実行、ログ上限を検証します。
変更履歴
1.3.1
- 同梱のPlugin Update Checkerを公式v5.7へ更新
1.3.0
- 入出力ディレクトリ、明示エントリーポイント、再帰検出を設定化
- 内容ハッシュとscssphp依存ファイルによる差分コンパイル
- 状態、失敗抑制、手動再コンパイル、管理画面ログを追加
- CSSキャッシュ更新補助と所有管理されたソースマップ削除を追加
- 公開ディレクトリへの新規エラーログ書き込みを廃止
1.2.0
- 設定式のCSSデバッグ、展開CSS、外部ソースマップを追加