SPFx 1.23.2: aktualisieren heißt nicht, eine Nummer zu ändern
Die vorige Version wurde wegen Regressionen aus npm zurückgezogen, und das ist die Warnung: Das Risiko einer SharePoint-Framework-Aktualisierung liegt fast nie in der SharePoint-Laufzeit, es liegt im Build. Was sich in Heft, in Sass und in npm audit geändert hat, mit dem Code, der zeigt, wie es war, wie es ist, und wie es sein wird.
SharePoint Framework 1.23.2 erschien am 30. Juni 2026 als Minor Bump: Es behebt npm-Schwachstellen und einige gemeldete Probleme. Es sieht aus wie eine Routineaktualisierung, von der Sorte, die man ohne Nachdenken macht. Ist es nicht.
Der Hinweis steckt in der vorigen Version. 1.23.1 wurde veröffentlicht und dann wegen Regressionen aus npm zurückgezogen. In einem reifen Framework ist eine aus dem Verkehr gezogene Version eine Warnung: Das Risiko einer SPFx-Aktualisierung liegt fast nie in der SharePoint-Laufzeit, es liegt im Build. Dieser Artikel handelt davon, was sich geändert hat, was zerbrochen ist, und was noch zerbrechen wird, mit dem Code, der zeigt, wie es war, wie es ist, und wie es sein wird.
Was zerbricht, ist nicht SharePoint, es ist der Build
Ein SPFx-Webpart läuft im Browser, in einer SharePoint-Seite, und dieser Teil ist seit Jahren stabil. Was Microsoft bewegt, und kräftig, ist die Build-Kette: das Werkzeug, das das TypeScript kompiliert, das Sass verarbeitet und das .sppkg packt. Die SPFx-Pakete zu aktualisieren und den Build-Prozess zu migrieren sind zwei verwandte Dinge, aber nicht dasselbe, und es ist das zweite, das Builds kaputt macht.
Daher Regel Nummer eins: eine SPFx-Aktualisierung ist nicht mechanisch. Man ändert nicht die Nummer in package.json und erwartet, dass es kompiliert, Microsoft selbst warnt, dass das zu Build-Fehlern führt. Es folgen die vier Stellen, an denen das beißt, und was an jeder zu tun ist.
Gulp ist auf dem Weg hinaus
Die strukturelle Änderung ist das Ende von Gulp. Bis 1.21 orchestrierte Gulp alles. Ab 1.22 wechselten neue Projekte zu Heft, das darunter weiter webpack nutzt, aber von ihm gesteuert; die gulpfile.js ist nicht mehr kompatibel und die config.json verschwand. In 1.23 kann ein bestehendes Projekt noch bei Gulp bleiben. In 1.24 wird Gulp offiziell nicht mehr unterstützt.
# WAS (SPFx 1.21 and earlier): Gulp orchestrated the whole build.
gulp bundle --ship
gulp package-solution --ship
# IS (SPFx 1.22-1.23): Heft orchestrates webpack. gulpfile.js and config.json
# are gone; the commands are plain npm scripts.
npm run build
npm run package
# WILL BE (SPFx 1.24): the Gulp toolchain is officially unsupported, and the
# Yeoman generator gives way to the new SPFx CLI.
npm install -g @microsoft/spfx-cli
Gleichzeitig wird Yeoman durch die neue @microsoft/spfx-cli ersetzt, noch als Vorabversion, mit allgemeiner Verfügbarkeit geplant für 1.25, im September. Mit anderen Worten: an den Paketen zu drehen und den Build zu migrieren sind getrennte Projekte. Man aktualisiert zuerst auf 1.23.2 und plant die Migration zu Heft getrennt, mit Tests.
Sass hat sich ohne Vorwarnung geändert
Die Regression, die in 1.23 am schwersten zu fassen ist, steckt in Sass, und Microsoft selbst stuft sie als undokumentiert ein (Issue #10854). Imports, die in 1.22 funktionierten, lösen nicht mehr auf: das Präfix ~, die Bare Specifiers und importIncludePaths funktionieren nicht mehr. Ein Projekt mit ernsthaftem Sass kompiliert in 1.22 und scheitert in 1.23, ohne eine einzige geänderte Codezeile.
// WAS (worked in SPFx 1.22): the webpack tilde and importIncludePaths.
@use "~@scope/package/styles";
@use "sass:meta";
.card { @include meta.load-css("~@scope/package/styles"); }
// IS (SPFx 1.23, issue #10854): the tilde and bare specifiers stop resolving,
// and importIncludePaths is gone. Import npm packages with the pkg: scheme.
@use "pkg:@scope/package/styles";
@use "sass:meta";
.card { @include meta.load-css("pkg:@scope/package/styles"); }
Der Weg ist das pkg:-Schema, um npm-Pakete zu importieren, und jedes meta.load-css() zu prüfen. Es gibt mehr im selben Bündel: die SCSS-Source-Maps zeigten auf Zwischen-CSS statt auf das ursprüngliche .scss (#10831), und schlichte .scss-Dateien erzeugten CSS-Module-Typen, obwohl webpack sie als global behandelte (#10832). 1.23.2 gibt das als behoben aus, aber einige Issues bleiben im Tracker offen: teste, bevor du annimmst, dass es in deinem Szenario gelöst ist.
npm audit fix --force schadet mehr, als es nützt
1.23.2 hat die kritischen und hohen Schwachstellen behoben, und es bleiben einige mittlere in externen Abhängigkeiten. Die instinktive Reaktion, npm audit fix --force auszuführen, ist die falsche, und Microsoft sagt ausdrücklich, es nicht zu tun: es schreibt transitive Pakete um, die Microsoft getestet hat, und hinterlässt einen Build, der sich nicht mehr reproduzieren lässt.
# WAS (the footgun Microsoft tells you not to pull): rewrites the transitive
# packages Microsoft tested, and leaves you a build that no longer reproduces.
npm audit fix --force
# IS (look before you touch): most vulnerable packages are build-time only, and
# node_modules never ships inside the .sppkg.
npm audit --omit=dev
npm ls the-flagged-package
npm explain the-flagged-package
Die Unterscheidung, die zählt: Die meisten verwundbaren Abhängigkeiten gehören zur Build-Umgebung, und das node_modules geht nie in das .sppkg. Eine Schwachstelle in einem lokalen Werkzeug ist keine Schwachstelle in der Produktion auf SharePoint. Bevor du etwas anfasst, prüfe, ob die Abhängigkeit nur zur Entwicklung gehört, ob sie im finalen Bundle landet, und wer sie hereingebracht hat.
Versionen festnageln, nicht @latest
Die Lektion von 1.23.1 ist diese: In einer Pipeline ist @latest eine Zeitbombe. Hätte der Build 1.23.1 am falschen Tag erwischt, hätte er eine Version installiert, die Microsoft am Ende zurückzog. Man nagelt exakte Versionen fest und installiert React genau so, wie die Matrix es vorgibt, mit --save-exact, denn eine falsche React-Version scheitert still, ohne Build-Fehler.
# The 1.23.1 lesson: it was delisted from npm for regressions. In a pipeline,
# @latest is a time bomb. Pin exact versions.
npm install react@17.0.1 react-dom@17.0.1 --save-exact
# SPFx 1.23.2 matrix: Node v22, TypeScript up to 5.8, React 17.0.1. Not 18 yet.
Die Matrix von 1.23.2 ist klar: Node v22, TypeScript bis 5.8, React 17.0.1. SPFx macht noch kein React 18, es steht weiter auf der Roadmap. Festnageln ist keine Bürokratie: es ist das, was einen Build, der sich reproduziert, von einem trennt, der sich zwischen einer Maschine und der Pipeline unter den Füßen verschiebt.
Und 1.24?
1.24 ist in der Vorschau, in der Beta seit dem 8. Juli 2026, und bringt die Neuerung, die zeigt, wohin SPFx geht: die SharePoint Copilot Apps. Es sind SPFx-Komponenten, mit derselben Paketierung und denselben Werkzeugen, aber sie rendern im Canvas von Microsoft 365 Copilot statt in einer SharePoint-Seite. Eine Copilot-Komponente erweitert BaseCopilotComponent, nicht BaseClientSideWebPart, und ein einziges .sppkg kann beide fassen.
Es ist eine echte Vorschau, und Microsoft steht dazu: sie rendert nur im Copilot-Canvas, sie wird nicht über den Store verteilt, und der Name selbst kann sich vor der finalen Version ändern. Es ist fürs Labor, in einem Entwicklungs-Tenant, nicht für die Produktion. Das Signal, das zählt, ist die Richtung: SPFx ist nicht mehr nur für SharePoint, sondern wird der Weg, eine eigene Oberfläche in Copilot zu bringen.
Was bleibt
1.23.2 ist die richtige Version für neue Projekte in der Produktion, aber man behandelt sie nicht wie einen Tausch einer Nummer. Die SharePoint-Laufzeit hält; was zerbricht, ist die Build-Kette, die Sass-Imports, die Gulp-Anpassungen, die in 1.24 sterben, und Funktionen, deren serverseitiger Rollout noch nicht fertig ist. Ein SPFx-Upgrade ist eine als Bump getarnte Build-Migration. Nagle die Versionen fest, teste den Build, und mach die Migration zu Heft mit einem Plan, nicht mit einem npm install.
