Konfigurowanie usługi Azure Static Web Apps

Konfigurację usługi Azure Static Web Apps można zdefiniować w pliku staticwebapp.config.json , który kontroluje następujące ustawienia:

• Trasowanie
• Uwierzytelnianie
• Autoryzacja
• Reguły rezerwowe
• Modyfikacje odpowiedzi HTTP
• Globalne definicje nagłówków HTTP
• Niestandardowe typy MIME
• Sieć

Uwaga

routes.json, który był wcześniej używany do konfigurowania routingu, jest przestarzały. Użyj staticwebapp.config.json zgodnie z opisem w tym artykule, aby skonfigurować routing i inne ustawienia statycznej aplikacji internetowej.

W tym dokumencie opisano sposób konfigurowania usługi Azure Static Web Apps, która jest produktem autonomicznym i oddzielnym od funkcji hostingu statycznej witryny internetowej w usłudze Azure Storage.

Lokalizacja pliku

Zalecane położenie dla pliku staticwebapp.config.json to folder ustawiony jako app_location w pliku workflow. Można jednak umieścić plik w dowolnym podfolderze w folderze ustawionym jako app_location. Ponadto jeśli istnieje krok kompilacji, musisz upewnić się, że krok kompilacji wyprowadza plik do katalogu głównego output_location.

Aby uzyskać szczegółowe informacje, zobacz przykładowy plik konfiguracji .

Ważne

Przestarzały plik routes.json jest ignorowany, jeśli istnieje staticwebapp.config.json.

Trasy

Reguły dla co najmniej jednej trasy można zdefiniować w statycznej aplikacji internetowej. Reguły tras umożliwiają ograniczenie dostępu do użytkowników w określonych rolach lub wykonywanie akcji, takich jak przekierowanie lub ponowne zapisywanie. Trasy są definiowane jako tablica reguł routingu. Zobacz przykładowy plik konfiguracji, aby zapoznać się z przykładami użycia.

• Reguły są definiowane w tablicy routes , nawet jeśli masz tylko jedną trasę.
• Reguły są oceniane w kolejności wyświetlanej w tablicy routes .
• Ocena reguły zatrzymuje się przy pierwszym dopasowaniu. Dopasowanie występuje, gdy route właściwość i wartość w methods tablicy (jeśli określono) są zgodne z żądaniem. Każde żądanie może być zgodne z co najwyżej jedną regułą.

Problemy z routingiem znacznie nakładają się na uwierzytelnianie (identyfikowanie użytkownika) i autoryzację (przypisywanie możliwości do użytkownika). Zapoznaj się z przewodnikiem uwierzytelniania i autoryzacji wraz z tym artykułem.

Definiowanie tras

Każda reguła składa się ze wzorca trasy wraz z co najmniej jedną właściwością reguły opcjonalnej. Reguły tras są definiowane w tablicy routes . Zobacz przykładowy plik konfiguracji, aby zapoznać się z przykładami użycia.

Ważne

Właściwości route oraz methods (jeśli określono) są jedynymi używanymi do określenia, czy reguła jest zgodna z żądaniem.

Właściwość Reguły	Wymagane	Domyślna wartość	Komentarz
route	Tak	nie dotyczy	Wzorzec trasy żądany przez dzwoniącego. Symbole wieloznaczne są obsługiwane na końcu ścieżek tras. Na przykład trasa /admin* pasuje do dowolnej trasy rozpoczynającej się od /admin.
methods	Nie.	Wszystkie metody	Definiuje tablicę metod żądań pasujących do trasy. Dostępne metody obejmują: GET, HEADPOSTPUTDELETECONNECTOPTIONS, , TRACEi .PATCH
rewrite	Nie.	nie dotyczy	Definiuje plik lub ścieżkę zwróconą z żądania. Wyklucza się wzajemnie z regułą redirect. Reguły ponownego zapisywania nie zmieniają lokalizacji przeglądarki. Wartości muszą być względne względem katalogu głównego aplikacji.
redirect	Nie.	nie dotyczy	Definiuje miejsce docelowe przekierowania pliku lub ścieżki dla żądania. Wyklucza się wzajemnie z regułą rewrite. Reguły przekierowania zmieniają lokalizację przeglądarki. Domyślny kod odpowiedzi to 302 (tymczasowe przekierowanie), ale można zastąpić elementem 301 (trwałe przekierowanie).
statusCode	Nie.	301 lub 302 dla przekierowań	Kod stanu HTTP odpowiedzi.
headers	Nie.	nie dotyczy	Zestaw nagłówków HTTP dodanych do odpowiedzi. Nagłówki specyficzne dla trasy zastępują globalHeaders, gdy nagłówek specyficzny dla trasy jest taki sam jak nagłówek globalny w odpowiedzi. Aby usunąć nagłówek, ustaw wartość na pusty ciąg.
allowedRoles	Nie.	anonimowy	Definiuje tablicę nazw ról wymaganych do uzyskania dostępu do trasy. Prawidłowe znaki to a-z, , A-Z0-9i _. Wbudowana rola, anonymous, ma zastosowanie do wszystkich użytkowników. Wbudowana rola, authenticated, ma zastosowanie do każdego zalogowanego użytkownika. Użytkownicy muszą należeć do co najmniej jednej roli. Role są dopasowywane na podstawie or . Jeśli użytkownik znajduje się w dowolnej z wymienionych ról, zostanie udzielony dostęp. Indywidualni użytkownicy są powiązani z rolami za pośrednictwem zaproszeń.

Każda właściwość ma określony cel w potoku żądania/odpowiedzi.

Cel	Właściwości
Dopasowywanie tras	route, methods
Przetwarzanie po dopasowaniu i autoryzacji reguły	rewrite (modyfikuje żądanie) redirect, , headersstatusCode (modyfikuje odpowiedź)
Autoryzowanie po dopasowaniu trasy	allowedRoles

Określanie wzorców tras

Właściwość route może być dokładną trasą lub wzorcem z symbolami wieloznacznymi.

Dokładna trasa

Aby zdefiniować dokładną trasę, umieść pełną ścieżkę pliku we route właściwości .

{
  "route": "/profile/index.html",
  "allowedRoles": ["authenticated"]
}

Ta reguła pasuje do żądań dla pliku /profile/index.html. Ponieważ index.html jest plikiem domyślnym, reguła odpowiada również żądaniom folderu (/profile lub /profile/).

Ważne

Jeśli używasz ścieżki folderu (/profile lub /profile/) we route właściwości, nie będzie ona zgodna z żądaniami dla pliku /profile/index.html. W przypadku ochrony trasy obsługującej plik należy zawsze używać pełnej ścieżki pliku, takiej jak /profile/index.html.

Wzorzec z symbolami wieloznacznymi

Reguły wieloznaczne dopasowują się do wszystkich żądań we wzorcu trasy i są obsługiwane tylko na jej końcu. Zobacz przykładowy plik konfiguracji, aby zapoznać się z przykładami użycia.

Na przykład w celu zaimplementowania tras dla aplikacji kalendarza można ponownie zapisać wszystkie adresy URL, które należą do trasy kalendarza , aby obsłużyć pojedynczy plik.

{
  "route": "/calendar*",
  "rewrite": "/calendar.html"
}

Plik calendar.html może następnie użyć routingu po stronie klienta, aby obsłużyć inny widok dla odmian adresów URL, takich jak /calendar/january/1, /calendar/2020i /calendar/overview.

Uwaga

Wzór trasy /calendar/* odpowiada wszystkim żądaniom w ramach ścieżki /calendar/. Jednak nie będzie on zgodny z żądaniami ścieżek /calendar lub /calendar.html. Służy /calendar* do dopasowywania wszystkich żądań rozpoczynających się od /calendar.

Symbole wieloznaczne można filtrować według rozszerzenia pliku. Jeśli na przykład chcesz dodać regułę zgodną tylko z plikami HTML w danej ścieżce, możesz utworzyć następującą regułę:

{
  "route": "/articles/*.html",
  "headers": {
    "Cache-Control": "public, max-age=604800, immutable"
  }
}

Aby filtrować wiele rozszerzeń plików, należy uwzględnić opcje w nawiasach klamrowych, jak pokazano w tym przykładzie:

{
  "route": "/images/thumbnails/*.{png,jpg,gif}",
  "headers": {
    "Cache-Control": "public, max-age=604800, immutable"
  }
}

Typowe przypadki użycia tras wieloznacznych obejmują:

• Serwowanie określonego pliku dla całego wzorca ścieżki
• Wymuszanie reguł uwierzytelniania i autoryzacji
• Implementowanie wyspecjalizowanych reguł buforowania

Zabezpieczanie tras przy użyciu ról

Trasy są zabezpieczone przez dodanie co najmniej jednej nazwy ról do tablicy allowedRoles reguły. Zobacz przykładowy plik konfiguracji, aby zapoznać się z przykładami użycia.

Ważne

Reguły routingu mogą zabezpieczać tylko żądania HTTP do tras obsługiwanych przez usługę Static Web Apps. Wiele frameworków front-endowych używa routingu po stronie klienta, który modyfikuje trasy w przeglądarce bez wysyłania żądań do Static Web Apps. Reguły routingu nie zabezpieczają tras po stronie klienta. Klienci powinni wywoływać interfejsy API HTTP w celu pobrania poufnych danych. Przed zwróceniem danych upewnij się, że interfejsy API weryfikują tożsamość użytkownika.

Domyślnie każdy użytkownik należy do wbudowanej anonymous roli, a wszyscy zalogowani użytkownicy są członkami authenticated roli. Opcjonalnie użytkownicy są powiązani z rolami niestandardowymi za pośrednictwem zaproszeń.

Aby na przykład ograniczyć trasę tylko do uwierzytelnionych użytkowników, dodaj wbudowaną authenticated rolę do tablicy allowedRoles .

{
  "route": "/profile*",
  "allowedRoles": ["authenticated"]
}

Nowe role można tworzyć zgodnie z potrzebami w tablicy allowedRoles . Aby ograniczyć trasę tylko do administratorów, możesz zdefiniować własną rolę o nazwie administrator, w tablicy allowedRoles .

{
  "route": "/admin*",
  "allowedRoles": ["administrator"]
}

• Masz pełną kontrolę nad nazwami ról; nie ma listy, do której muszą pasować role.
• Indywidualni użytkownicy są powiązani z rolami za pośrednictwem zaproszeń.

Ważne

Podczas zabezpieczania zawartości określ dokładne pliki, jeśli to możliwe. Jeśli masz wiele plików do zabezpieczenia, użyj symboli wieloznacznych po prefiksie udostępnionym. Na przykład: /profile* zabezpiecza wszystkie możliwe trasy rozpoczynające się od /profile, w tym /profile.

Ograniczanie dostępu do całej aplikacji

Często chcesz wymagać uwierzytelniania dla każdej trasy w aplikacji. Aby zablokować trasy, dodaj regułę pasującą do wszystkich tras i dołącz wbudowaną rolę authenticated do tablicy allowedRoles.

Poniższa przykładowa konfiguracja blokuje dostęp anonimowy i przekierowuje wszystkich nieuwierzytelnionych użytkowników do strony logowania firmy Microsoft Entra.

{
  "routes": [
    {
      "route": "/*",
      "allowedRoles": ["authenticated"]
    }
  ],
  "responseOverrides": {
    "401": {
      "statusCode": 302,
      "redirect": "/.auth/login/aad"
    }
  }
}

Uwaga

Domyślnie wszyscy wstępnie skonfigurowani dostawcy tożsamości są włączeni. Aby zablokować dostawcę uwierzytelniania, zobacz Uwierzytelnianie i autoryzacja.

Trasy rezerwowe

Aplikacje jednostronicowe często korzystają z routingu po stronie klienta. Te zasady routingu po stronie klienta aktualizują lokalizację okna przeglądarki bez wysyłania żądań do serwera. Jeśli odświeżysz stronę lub przejdziesz bezpośrednio do adresów URL generowanych przez reguły routingu po stronie klienta, trasa rezerwowa po stronie serwera jest wymagana do obsługi odpowiedniej strony HTML. Strona rezerwowa jest często wyznaczona jako index.html dla aplikacji po stronie klienta.

Uwaga

Reguły tras nie są stosowane dla żądań wyzwalających navigationFallback.

Regułę rezerwową można zdefiniować, dodając sekcję navigationFallback . Poniższy przykład zwraca /index.html dla wszystkich żądań plików statycznych, które nie są zgodne z wdrożonym plikiem.

{
  "navigationFallback": {
    "rewrite": "/index.html"
  }
}

Możesz kontrolować, które żądania zwracają plik rezerwowy, definiując filtr. W poniższym przykładzie żądania dotyczące niektórych tras w folderze /images i wszystkie pliki w folderze /css są wykluczone z zwracania pliku rezerwowego.

{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/images/*.{png,jpg,gif}", "/css/*"]
  }
}

Na przykład w poniższej strukturze katalogów, powyższa reguła zapasowa nawigacji spowoduje wyniki przedstawione w poniższej tabeli.

├── images
│   ├── logo.png
│   ├── headshot.jpg
│   └── screenshot.gif
│
├── css
│   └── global.css
│
├── about.html
└── index.html

Żądania do...	Zwraca...	z aktualnym stanem...
/około/	Plik /index.html.	200
/images/logo.png	Plik obrazu.	200
/images/icon.svg	Plik /index.html — ponieważ rozszerzenie pliku svg nie jest wymienione w filtrze/images/*.{png,jpg,gif}.	200
/images/unknown.png	Błąd: nie znaleziono pliku.	404
/css/unknown.css	Błąd: nie znaleziono pliku.	404
/css/global.css	Plik arkusza stylów.	200
/about.html	Strona HTML.	200
Każda inna ścieżka poza folderami /images lub /css , które nie są zgodne ze ścieżką do wdrożonego pliku.	Plik /index.html.	200

Ważne

Jeśli migrujesz z przestarzałego pliku routes.json, nie uwzględnij starszej trasy rezerwowej ("route": "/*") w regułach routingu.

Nagłówki globalne

Sekcja globalHeaders zawiera zestaw nagłówków HTTP zastosowanych do każdej odpowiedzi, chyba że zostanie zastąpiona przez regułę nagłówka trasy. W przeciwnym razie, zwracane jest połączenie nagłówków z trasy oraz globalnych nagłówków.

Zobacz przykładowy plik konfiguracji, aby zapoznać się z przykładami użycia.

Aby usunąć nagłówek, ustaw wartość na pusty ciąg ("").

Oto niektóre typowe przypadki użycia nagłówków globalnych:

• Niestandardowe reguły buforowania
• Zasady zabezpieczeń
• Ustawienia kodowania
• Konfiguracja współużytkowania zasobów między źródłami (CORS)

Poniższy przykład implementuje niestandardową konfigurację mechanizmu CORS.

{
  "globalHeaders": {
    "Access-Control-Allow-Origin": "https://example.com",
    "Access-Control-Allow-Methods": "POST, GET, OPTIONS"
  }
}

Uwaga

Nagłówki globalne nie mają wpływu na odpowiedzi interfejsu API. Nagłówki w odpowiedziach interfejsu API są zachowywane i zwracane do klienta.

Przesłonięcia odpowiedzi

Sekcja responseOverrides zawiera możliwość zdefiniowania odpowiedzi niestandardowej, gdy serwer w przeciwnym razie zwróci kod błędu. Zobacz przykładowy plik konfiguracji, aby zapoznać się z przykładami użycia.

Następujące kody HTTP są dostępne do zastąpienia:

Kod stanu	Znaczenie	Możliwa przyczyna
400	Nieprawidłowe żądanie	Nieprawidłowy link do zaproszenia
401	Brak autoryzacji	Żądanie dostępu do stron z ograniczeniami bez uwierzytelnienia
403	Dostęp zabroniony	Użytkownik jest zalogowany, ale nie ma ról wymaganych do wyświetlenia strony. Użytkownik jest zalogowany, ale środowisko uruchomieniowe nie może uzyskać szczegółów użytkownika z oświadczeń tożsamości. Witryna ma zbyt wielu użytkowników z niestandardowymi rolami, dlatego środowisko uruchomieniowe nie może zalogować użytkownika.
404	Nie znaleziono	Nie znaleziono pliku

Poniższa przykładowa konfiguracja pokazuje, jak zastąpić kod błędu.

{
  "responseOverrides": {
    "400": {
      "rewrite": "/invalid-invitation-error.html"
    },
    "401": {
      "statusCode": 302,
      "redirect": "/login"
    },
    "403": {
      "rewrite": "/custom-forbidden-page.html"
    },
    "404": {
      "rewrite": "/custom-404.html"
    }
  }
}

Platforma

Sekcja platform steruje ustawieniami specyficznymi dla platformy, takimi jak wersja środowiska uruchomieniowego języka interfejsu API.

Wybierz wersję środowiska uruchomieniowego języka API

Aby skonfigurować wersję środowiska uruchomieniowego języka interfejsu API, ustaw właściwość apiRuntime w sekcji platform na jedną z następujących obsługiwanych wartości.

Wersja środowiska uruchomieniowego języka	System operacyjny	Wersja usługi Azure Functions	apiRuntime wartość	Data zakończenia pomocy technicznej
.NET Core 3.1	Windows	3.x	dotnet:3.1	3 grudnia 2022 r.
.NET 6.0 wewnątrz procesu	Windows	4.x	dotnet:6.0	30 kwietnia 2025 r.
Proces platformy .NET 8.0	Windows	4.x	dotnet:8.0	-
Izolowane środowisko .NET 6.0	Windows	4.x	dotnet-isolated:6.0	30 kwietnia 2025 r.
Izolowany program .NET 7.0	Windows	4.x	dotnet-isolated:7.0	30 kwietnia 2025 r.
Izolowany program .NET 8.0	Windows	4.x	dotnet-isolated:8.0	-
Izolowany program .NET 9.0	Windows	4.x	dotnet-isolated:9.0	-
Node.js 12.x	Linux	3.x	node:12	3 grudnia 2022 r.
Node.js 14.x	Linux	4.x	node:14	30 kwietnia 2025 r.
Node.js 16.x	Linux	4.x	node:16	30 kwietnia 2025 r.
Node.js 18.x	Linux	4.x	node:18	31 maja 2025
Node.js 20.x	Linux	4.x	node:20	-
Python 3.8	Linux	4.x	python:3.8	30 kwietnia 2025 r.
Python 3.9	Linux	4.x	python:3.9	-
Python 3.10	Linux	4.x	python:3.10	-
Python 3.11	Linux	4.x	python:3.11	-

.NET

Aby zmienić wersję środowiska uruchomieniowego w aplikacji .NET, zmień TargetFramework wartość w pliku csproj . Jeśli opcjonalnie ustawisz wartość apiRuntime w pliku staticwebapp.config.json, upewnij się, że wartość ta jest zgodna z definicją w pliku csproj.

W poniższym przykładzie pokazano, jak zaktualizować element TargetFramework dla wersji środowiska uruchomieniowego języka API w wersji NET 8.0 w pliku csproj.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    ...
  </PropertyGroup>
...

Node.js

Poniższa przykładowa konfiguracja pokazuje, jak używać właściwości apiRuntime do wyboru wersji językowej środowiska uruchomieniowego API Node.js 20 w pliku staticwebapp.config.json.

{
  ...
  "platform": {
    "apiRuntime": "node:20"
  }
  ...
}

Pyton

Poniższa przykładowa konfiguracja pokazuje, jak używać apiRuntime właściwości do wybierania języka Python 3.11 jako wersji środowiska uruchomieniowego języka interfejsu API w pliku staticwebapp.config.json .

{
  ...
  "platform": {
    "apiRuntime": "python:3.11"
  }
  ...
}

Nawiązywanie kontaktów

Sekcja networking steruje konfiguracją sieci statycznej aplikacji internetowej. Aby ograniczyć dostęp do aplikacji, określ listę dozwolonych bloków adresów IP w pliku allowedIpRanges. Aby uzyskać więcej informacji na temat liczby dozwolonych bloków adresów IP, zapoznaj się z Limitami w usłudze Azure Static Web Apps.

Uwaga

Konfiguracja sieci jest dostępna tylko w planie Standard usługi Azure Static Web Apps.

Zdefiniuj każdy blok adresów IPv4 w notacji CIDR (Classless Inter-Domain Routing). Aby dowiedzieć się więcej na temat notacji CIDR, zobacz Bezklasowy routing międzydomenowy. Każdy blok adresów IPv4 może oznaczać przestrzeń adresową publiczną lub prywatną. Jeśli chcesz zezwolić na dostęp tylko z jednego adresu IP, możesz użyć /32 bloku CIDR.

{
  "networking": {
    "allowedIpRanges": [
      "10.0.0.0/24",
      "100.0.0.0/32",
      "192.168.100.0/22"
    ]
  }
}

Po określeniu co najmniej jednego bloku adresów IP żądania pochodzące z adresów IP, które nie pasują do wartości w allowedIpRanges elemecie, są blokowane.

Oprócz bloków adresów IP można również określić tagi usług w allowedIpRanges tablicy, aby ograniczyć ruch do niektórych usług platformy Azure.

"networking": {
  "allowedIpRanges": ["AzureFrontDoor.Backend"]
}

Uwierzytelnianie

• Domyślni dostawcy uwierzytelniania nie wymagają ustawień w pliku konfiguracji.

• Niestandardowi dostawcy uwierzytelniania używają sekcji auth w pliku ustawień.

Aby uzyskać szczegółowe informacje na temat ograniczania tras do uwierzytelnionych użytkowników, zobacz Zabezpieczanie tras z rolami.

Wyłącz pamięć podręczną dla uwierzytelnionych ścieżek

Jeśli skonfigurujesz ręczną integrację z usługą Azure Front Door, możesz wyłączyć buforowanie dla zabezpieczonych tras. Włączając brzeg klasy korporacyjnej, buforowanie jest już wyłączone dla zabezpieczonych tras.

Aby wyłączyć buforowanie usługi Azure Front Door dla zabezpieczonych tras, dodaj "Cache-Control": "no-store" do definicji nagłówka trasy.

Na przykład:

{
    "route": "/members",
    "allowedRoles": ["authenticated, members"],
    "headers": {
        "Cache-Control": "no-store"
    }
}

Brama przekazująca

W forwardingGateway sekcji opisano sposób uzyskiwania dostępu do statycznej aplikacji internetowej z bramy przekazywania, takiej jak usługa Content Delivery Network (CDN) lub usługa Azure Front Door.

Uwaga

Konfiguracja bramy przekazywania jest dostępna tylko w planie Standard Statycznych Aplikacji Webowych Azure.

Dozwolone przekazywane hosty

Lista allowedForwardedHosts określa, które nazwy hostów mają być akceptowane w nagłówku X-Forwarded-Host . Jeśli pasująca domena znajduje się na liście, usługa Static Web Apps używa wartości X-Forwarded-Host podczas konstruowania adresów URL przekierowania, na przykład po pomyślnym zalogowaniu.

Aby usługa Static Web Apps działała poprawnie przez bramę przekazującą, żądanie z tej bramy musi zawierać prawidłową nazwę hosta w nagłówku X-Forwarded-Host, a ta sama nazwa hosta musi być podana w allowedForwardedHosts.

"forwardingGateway": {
  "allowedForwardedHosts": [
    "example.org",
    "www.example.org",
    "staging.example.org"
  ]
}

X-Forwarded-Host Jeśli nagłówek nie pasuje do wartości na liście, żądania nadal kończą się powodzeniem, ale nagłówek nie jest używany w odpowiedzi.

Wymagane nagłówki

Wymagane nagłówki to nagłówki HTTP, które muszą być wysyłane z każdym żądaniem do witryny. Jednym z zastosowań wymaganych nagłówków jest odmowa dostępu do witryny, jeśli w każdym żądaniu nie są obecne wszystkie niezbędne nagłówki.

Na przykład poniższa konfiguracja pokazuje, jak dodać unikatowy identyfikator usługi Azure Front Door, który ogranicza dostęp do witryny z określonego wystąpienia usługi Azure Front Door . Aby uzyskać szczegółowe informacje, zobacz samouczek Konfigurowanie usługi Azure Front Door.

"forwardingGateway": {
  "requiredHeaders": {
    "X-Azure-FDID" : "692a448c-2b5d-4e4d-9fcc-2bc4a6e2335f"
  }
}

• Pary klucz/wartość mogą być dowolnym zestawem dowolnych ciągów
• Klucze są niewrażliwe na wielkość liter
• W wartościach uwzględniana jest wielkość liter

Ukośnik końcowy

Końcowy ukośnik to / na końcu adresu URL. Konwencjonalnie adres URL z końcowym ukośnikiem odnosi się do katalogu na serwerze internetowym, podczas gdy adres URL bez ukośnika wskazuje na plik.

Aparaty wyszukiwania traktują dwa adresy URL oddzielnie, niezależnie od tego, czy jest to plik, czy katalog. Gdy ta sama zawartość jest renderowana na obu tych adresach URL, witryna internetowa udostępnia zduplikowaną zawartość, co może negatywnie wpłynąć na optymalizację aparatu wyszukiwania (SEO). W przypadku jawnego skonfigurowania usługa Static Web Apps stosuje zestaw reguł normalizacji adresów URL i przekierowania, które pomagają poprawić wydajność witryny internetowej i wydajność optymalizacji wyszukiwania.

Dla każdej z dostępnych konfiguracji mają zastosowanie następujące reguły normalizacji i przekierowania:

Zawsze

Po ustawieniu wartości trailingSlash na always, wszystkie żądania, które nie zawierają ukośnika końcowego, są przekierowywane do adresu URL z ukośnikiem końcowym. Na przykład /contact jest przekierowywany do /contact/.

"trailingSlash": "always"

Żądania do...	Zwraca...	z aktualnym stanem...	i ścieżka...
/about	Plik /about/index.html	301	/około/
/około/	Plik /about/index.html	200	/około/
/about/index.html	Plik /about/index.html	301	/około/
/privacy.html	Plik /privacy.html	301	/prywatność/

Nigdy

W przypadku ustawienia trailingSlash na never wszystkie żądania kończące się ukośnikiem są przekierowywane do adresu URL bez ukośnika na końcu. Na przykład /contact/ jest przekierowywany do /contact.

"trailingSlash": "never"

Żądania do...	Zwraca...	z aktualnym stanem...	i ścieżka...
/około	Plik /about/index.html	200	/o-nas
/około/	Plik /about/index.html	301	/o_nas
/about/index.html	Plik /about/index.html	301	/about
/privacy.html	Plik /privacy.html	301	/prywatność

Samochód

Po ustawieniu trailingSlash na auto, wszystkie żądania do folderów są przekierowywane do adresu URL z ukośnikiem na końcu. Wszystkie żądania do plików są przekierowywane do adresu URL bez ukośnika na końcu.

"trailingSlash": "auto"

Żądania do...	Zwraca...	z aktualnym stanem...	i ścieżka...
/około	Plik /about/index.html	301	/około/
/około/	Plik /about/index.html	200	/około/
/about/index.html	Plik /about/index.html	301	/około/
/privacy.html	Plik /privacy.html	301	/prywatność

Aby uzyskać optymalną wydajność witryny internetowej, skonfiguruj strategię ukośnika końcowego przy użyciu jednego z trybów always, never lub auto.

Domyślnie, gdy konfiguracja trailingSlash jest pomijana, usługa Static Web Apps stosuje następujące reguły:

Żądania do...	Zwraca...	z aktualnym stanem...	i ścieżka...
/około	Plik /about/index.html	200	/about
/około/	Plik /about/index.html	200	/około/
/about/index.html	Plik /about/index.html	200	/about/index.html
/privacy.html	Plik /privacy.html	200	/privacy.html

Przykładowa konfiguracja pliku

{
  "trailingSlash": "auto",
  "routes": [
    {
      "route": "/profile*",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/admin/index.html",
      "allowedRoles": ["administrator"]
    },
    {
      "route": "/images/*",
      "headers": {
        "cache-control": "must-revalidate, max-age=15770000"
      }
    },
    {
      "route": "/api/*",
      "methods": ["GET"],
      "allowedRoles": ["registeredusers"]
    },
    {
      "route": "/api/*",
      "methods": ["PUT", "POST", "PATCH", "DELETE"],
      "allowedRoles": ["administrator"]
    },
    {
      "route": "/api/*",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/customers/contoso*",
      "allowedRoles": ["administrator", "customers_contoso"]
    },
    {
      "route": "/login",
      "rewrite": "/.auth/login/github"
    },
    {
      "route": "/.auth/login/x",
      "statusCode": 404
    },
    {
      "route": "/logout",
      "redirect": "/.auth/logout"
    },
    {
      "route": "/calendar*",
      "rewrite": "/calendar.html"
    },
    {
      "route": "/specials",
      "redirect": "/deals",
      "statusCode": 301
    }
  ],
  "navigationFallback": {
    "rewrite": "index.html",
    "exclude": ["/images/*.{png,jpg,gif}", "/css/*"]
  },
  "responseOverrides": {
    "400": {
      "rewrite": "/invalid-invitation-error.html"
    },
    "401": {
      "redirect": "/login",
      "statusCode": 302
    },
    "403": {
      "rewrite": "/custom-forbidden-page.html"
    },
    "404": {
      "rewrite": "/404.html"
    }
  },
  "globalHeaders": {
    "content-security-policy": "default-src https: 'unsafe-eval' 'unsafe-inline'; object-src 'none'"
  },
  "mimeTypes": {
    ".json": "text/json"
  }
}

Na podstawie powyższej konfiguracji przejrzyj następujące scenariusze.

Żądania do...	wyniki...
/profil	Uwierzytelnieni użytkownicy otrzymują plik /profile/index.html. Niezweryfikowani użytkownicy są przekierowywani do /login przez regułę 401 nadpisania odpowiedzi.
/admin, /admin/lub /admin/index.html	Uwierzytelnieni użytkownicy w roli administratora są obsługiwani w pliku /admin/index.html . Uwierzytelnieni użytkownicy, którzy nie należą do roli administratora, otrzymują błąd4031. Użytkownicy nieuwierzytelnieni są przekierowywani do /login
/images/logo.png	Udostępnia obraz z niestandardową regułą pamięci podręcznej, w której maksymalny wiek wynosi nieco ponad 182 dni (15 770 000 sekund).
/api/admin	GET żądania od uwierzytelnionych użytkowników w roli zarejestrowanych użytkowników są wysyłane do interfejsu API. Użytkownicy uwierzytelnieni, którzy nie znajdują się w roli registeredusers, oraz użytkownicy nieuwierzytelnieni są obsługiwani komunikatem błędu 401. POSTżądania , , PUTPATCHi DELETE od uwierzytelnionych użytkowników w roli administratora są wysyłane do interfejsu API. Uwierzytelnieni użytkownicy, którzy nie mają roli administratora, oraz użytkownicy nieuwierzytelnieni otrzymują błąd 401.
/customers/contoso	Uwierzytelnieni użytkownicy, którzy należą do roli administratora lub customers_contoso , są obsługiwani w pliku /customers/contoso/index.html . Uwierzytelnieni użytkownicy, którzy nie znajdują się w roli administratora lub customers_contoso, wyświetlany jest błąd403. Nieuwierzytelnieni użytkownicy są przekierowywani do /login.
/login	Nieuwierzytelnieni użytkownicy są proszeni o uwierzytelnienie za pomocą GitHub.
_/.auth/login/x	Ponieważ reguła trasy wyłącza autoryzację X, zwracany jest błąd 404. Ten błąd powoduje ponowne podjęcie próby obsługi pliku /index.html i zwraca kod stanu 200.
/Wyloguj	Użytkownicy są wylogowani z dowolnego dostawcy uwierzytelniania.
/calendar/2021/01	Przeglądarka otrzymuje plik /calendar.html.
/Promocje	Przeglądarka jest trwale przekierowywana do /deals.
/data.json	Plik został udostępniony z typem MIME text/json.
/about, lub dowolny folder, który pasuje do wzorców routingu po stronie klienta	Plik /index.html jest obsługiwany przy użyciu 200 kodu stanu.
Nieistniejąca plik w folderze /images/	Błąd 404 .

¹ Możesz podać niestandardową stronę błędu przy użyciu reguły zastępowania odpowiedzi.

Ograniczenia

Istnieją następujące ograniczenia dla pliku staticwebapp.config.json .

• Maksymalny rozmiar pliku to 20 KB
• Maksymalnie 50 odrębnych ról

Zobacz artykuł Limity przydziału w celu uzyskania ogólnych ograniczeń.

Następne kroki

Konfigurowanie uwierzytelniania i autoryzacji

Powiązane artykuły

• Ustawianie ustawień na poziomie aplikacji i zmiennych środowiskowych używanych przez interfejsy API zaplecza
• Definiowanie ustawień sterujących procesem kompilacji