Kako odpraviti napako Django “ImproperlyConfigured: Nastavitev SECRET_KEY ne sme biti prazna”

Če Django sproži napako django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty, je neposredna težava preprosta: modul nastavitev, ki ga je Django naložil, ob izvajanju ne zagotavlja uporabne vrednosti SECRET_KEY. Popravite vrednost v modulu nastavitev, ki se dejansko uporablja, ali pa zagotovite, da spremenljivka okolja, ki jo zagotavlja, doseže proces Django. Ne rešujte napake v produkciji tako, da trajni skrivni ključ trajno shranite v nadzor različic.

Ta vodnik je bil preverjen glede na dokumentacijo Django 6.1. Django 6.1 je bil izdan 5. avgusta 2026. Osnovno pravilo je eksplicitno: SECRET_KEY ima privzeto vrednost prazen niz, mora biti unikaten in nepredvidljiv, Django pa zavrne zagon, če ni nastavljen. Glejte uradno referenco za nastavitev SECRET_KEY v Django.

Kaj dejansko pomeni “SECRET_KEY setting must not be empty”?

To pomeni, da je bila ob poskusu uporabe settings.SECRET_KEY v Django razrešena vrednost prazna ali pa je manjkala. V na novo ustvarjenem projektu django-admin startproject običajno zapiše generiran ključ v settings.py. Zato je ta napaka še posebej pogosta, ko je bil projekt preurejen za več okolij, prenesen na spremenljivke okolja, nameščen na novo storitev ali zagnan z drugačnim modulom nastavitev.

Prvo uporabno vprašanje ni “Kako naj izmislim poljuben niz, da se strežnik zažene?”, temveč “Od kod naj ta namestitev pridobi svoj skrivni ključ?”. Ta razlika je pomembna, ker bi morala obstoječa produkcijska aplikacija običajno obnoviti svoj namenjeni skrivni ključ, namesto da bi ob vsakem zagonu tiho generirala drugega.

Pogosti vzorci kode, ki povzročajo napako

SECRET_KEY = ""

# Manjkajoča spremenljivka okolja vrne None
SECRET_KEY = os.getenv("SECRET_KEY")

# Manjkajoča spremenljivka okolja tiho pade na prazen niz
SECRET_KEY = os.getenv("SECRET_KEY", "")

Vsi trije vzorci pustijo Django brez uporabnega skrivnega ključa, ko zunanja vrednost manjka. Za produkcijsko konfiguracijo Djangojev lasten kontrolni seznam za namestitev prikazuje obliko, ki takoj odpove:

import os

SECRET_KEY = os.environ["SECRET_KEY"]

Pri tem vzorcu manjkajoča spremenljivka okolja procesa takoj povzroči napako, namesto da bi tiho postala prazna vrednost. Uradni kontrolni seznam za namestitev Django tudi navaja, da bi moral biti produkcijski ključ velika naključna vrednost, ki ostane skrivna, se ne uporablja drugje in ni shranjena v nadzoru različic.

Katero datoteko nastavitev Django dejansko nalaga?

Pred urejanjem datoteke potrdite, da gre za datoteko, ki jo uporablja vaš ukaz ali aplikacijski strežnik. Django izbere modul nastavitev prek DJANGO_SETTINGS_MODULE, ki je Pythonova pot, kot je mysite.settings ali config.settings.production. Uradni vodnik za nastavitve Django dokumentira ta mehanizem in možnost ukazne vrstice --settings.

Na primer, spreminjanje config/settings.py ne bo pomagalo, če storitev zažene Django z:

python manage.py runserver --settings=config.settings.local

Prav tako lahko produkcijska vstopna točka WSGI ali ASGI nastavi drugačen modul. Preglejte manage.py, wsgi.py, asgi.py in dejanski ukaz strežnika ali konfiguracijo storitve. Če namerno uporabljate modul nastavitev za produkcijo, eksplicitno testirajte ta isti modul, namesto da testirate razvojno datoteko in predpostavljate, da se rezultat prenese.

Ali naj generirate nov SECRET_KEY ali obnovite starega?

Za povsem nov lokalni projekt: generiranje nove varne vrednosti je smiselno. Standardni Pythonov modul secrets je zasnovan za kriptografsko močno naključnost. En prenosljiv ukaz je:

python -c "import secrets; print(secrets.token_urlsafe(64))"

Dokumentacija Pythona opisuje secrets kot modul za generiranje varnih naključnih vrednosti, primernih za gesla, žetone za preverjanje pristnosti in sorodne skrivnosti. Glejte uradno dokumentacijo Python secrets.

Za obstoječo produkcijsko aplikacijo, ki je nekoč delovala: najprej poskusite obnoviti isti namenjeni skrivni ključ iz vaše shrambe skrivnosti ali konfiguracije namestitve. Django uporablja SECRET_KEY za kriptografsko podpisovanje in za več funkcij, vključno z določenimi konfiguracijami sej in sporočil ter žetoni za ponastavitev gesla. Nepričakovana zamenjava ključa lahko razveljavi podpisane podatke. Če stari ključ ni bil ogrožen in je izpad zgolj napaka pri vbrizgavanju okolja, obnova običajno prepreči nepotrebno rotacijo.

Če je bil stari ključ razkrit: ga zamenjajte (rotirajte). Django 6.1 podpira SECRET_KEY_FALLBACKS za načrtovano rotacijo, kar omogoča začasno sprejemanje starih ključev, medtem ko novo podpisovanje uporablja novi ključ. Odstranite rezervne ključe, ko je njihovo prehodno obdobje končano. Vedenje in kompromis sta dokumentirana v uradni referenci SECRET_KEY_FALLBACKS.

Kateri je najhitrejši varen popravek za lokalni razvoj?

Če poskušate zagnati le za enkratno uporabo namenjen lokalni projekt, lahko v aktivno datoteko nastavitev za dovolj dolgo, da potrdite diagnozo, vstavite generirano vrednost, ki je namenjena le razvoju:

SECRET_KEY = "replace-this-with-a-random-development-only-value"

Nato znova zaženite Django. Če napaka izgine, ste potrdili, da je bila prazna nastavitev ovira. Ne kopirajte produkcijskega skrivnega ključa na prenosnik razvijalca le zato, da bi bila lokalna nastavitev priročna, in ne obravnavajte trdo kodirane razvojne vrednosti kot vaš produkcijski načrt.

Ali spremenljivka okolja res dosega proces Django?

To je najpomembnejša preverba, ko vaša datoteka nastavitev že vsebuje SECRET_KEY = os.environ["SECRET_KEY"] ali enakovredno iskanje. Spremenljivka mora obstajati v okolju točno tistega procesa, ki uvaža nastavitve Django. Nastavitev v enem terminalu ne postavi samodejno v že tekočo storitev, kontejner, upravitelja procesov, CI opravilo ali ločen lupin.

Preverite prisotnost brez izpisa same skrivnosti:

python -c "import os; print(bool(os.environ.get('SECRET_KEY')))"

Če to izpiše False, popravite vbrizgavanje okolja za ta proces. Za hiter lokalni test lupine uporabite sintakso za svojo lupino in nato zaženite Django iz iste lupine. Na primer:

# macOS / Linux shell
export SECRET_KEY='your-generated-local-secret'
python manage.py runserver

# Windows PowerShell
$env:SECRET_KEY = 'your-generated-local-secret'
python manage.py runserver

Za produkcijo uporabite mehanizem za skrivnosti/konfiguracijo, ki ga zagotavlja vaša gostiteljska platforma ali upravitelj procesov, namesto da vrednost postavite v ukaz, ki bi lahko bil shranjen v zgodovini lupine.

Zakaj dodajanje SECRET_KEY v datoteko .env ni popravilo Django?

Datoteka .env je le datoteka, dokler je neka komponenta ne naloži v okolje procesa ali dokler je vaša koda nastavitev ne prebere. Djangojev uradni primer bere os.environ; Django ne zahteva niti ne dokumentira vgrajenega samodejnega koraka nalaganja .env. Če se vaš projekt zanaša na knjižnico dotenv, ovojnico ogrodja, konfiguracijo kontejnerja ali platformo za namestitev za nalaganje te datoteke, ločeno preverite to komponento in preverite, ali se izvede preden settings.py prebere SECRET_KEY.

Koristno dejanje je, da zgornjo logično preverbo okolja izvedete iz istega kontejnerja, računa storitve, lupine ali faze izvajanja, ki odpoveduje. Če izpiše False, razhroščevanje vsebine settings.py samo po sebi ne bo popravilo konfiguracijske težave na ravni procesa.

Kaj če se napaka pojavi le v Docker, CI, collectstatic, WSGI ali ASGI?

To običajno pomeni, da drugačen proces ali faza izvajanja nalaga projekt z drugačnim okoljem ali modulom nastavitev. Napaka se lahko pojavi med collectstatic, migracijami, testi, CI preverjanjem, zagonom aplikacijskega strežnika ali ozadnim procesom, čeprav runserver deluje na vašem prenosniku.

Ne predpostavljajte, da je skrivnost, ki je na voljo ob izvajanju, na voljo tudi med gradnjo slike ali korakom CI. Obratno, ne predpostavljajte, da je spremenljivka, izvožena v interaktivni lupini, vidna sistemu storitve. V neuspešnem kontekstu preverite ta dva dejstva:

• Katera vrednost DJANGO_SETTINGS_MODULE ali --settings se uporablja?
• Ali ima ta točen proces neprazno spremenljivko okolja SECRET_KEY, preden Django uvozi nastavitve?

Specifičen način vbrizgavanja skrivnosti je odvisen od Docker, vašega ponudnika CI, vašega gostitelja ali vašega upravitelja procesov. Uporabite uradni mehanizem za upravljanje skrivnosti te platforme. Zahteva na strani Django ostaja enaka: izbrana konfiguracija nastavitev mora ob izvajanju zagotoviti neprazen skrivni ključ.

Kako preverite popravek, ne da bi razkrili ključ?

Najprej ne izpisujte dejanskega produkcijskega ključa v dnevnike le zato, da dokažete, da obstaja. Prisotnost preverite z logično preverbo, nato pa pustite, da Django naloži konfiguracijo:

python manage.py check

Za produkcijsko konfiguracijo Django priporoča izvajanje kontrolnih preverjanj namestitve glede na produkcijsko datoteko nastavitev:

python manage.py check --deploy --settings=config.settings.production

Pot modula zamenjajte s svojim resničnim produkcijskim modulom nastavitev. Uradni kontrolni seznam za namestitev izrecno priporoča check --deploy in opozarja, da ga je treba izvesti glede na produkcijske nastavitve.

Na koncu znova zaženite dejanski proces aplikacije. Spremenljivka, dodana po zagonu storitve, običajno ne bo vplivala na že tekoči proces. Če ponovno zagnani proces opravi Djangojeva preverjanja in ne sproži več izjeme, je konfiguracijska težava rešena.

Katerih popravkov se morate izogibati?

• Ne nastavljajte SECRET_KEY = "" ali uporabljajte prazne privzete vrednosti. To ponovi pogoj, ki ga Django zavrne.
• Ne generirajte novega ključa ob vsakem zagonu aplikacije. Spreminjajoč se ključ lahko razveljavi podpisane podatke in ustvari nekonsistentno vedenje med več delavci.
• Ne kopirajte skrivnosti iz vadnice ali drugega projekta. Django zahteva unikaten, nepredvidljiv vrednost, javna vrednost pa uniči namen skrivnosti.
• Ne shranjujte produkcijskega ključa v Git. Kontrolni seznam za namestitev Django izrecno svetuje, da ga hranite zunaj nadzora različic.
• Ne izpisujte celotnega ključa v CI ali produkcijske dnevnike. Preverite le, ali je prisoten, razen če imate nadzorovan postopek revizije skrivnosti.
• Ne predpostavljajte, da je datoteka .env naložena zgolj zato, ker obstaja. Potrdite mehanizem nalaganja in dejansko okolje procesa.

Praktična pot odločanja

Končni kontrolni seznam

• Potrdite točen modul nastavitev, ki ga Django nalaga.
• Potrdite, da se SECRET_KEY v tem okolju razreši v neprazno vrednost.
• Uporabite unikaten, nepredvidljiv vrednost; ne uporabljajte javnega ali vadbenega ključa.
• Produkcijski ključ hranite zunaj nadzora različic.
• Če uporabljate spremenljivke okolja, zagotovite, da spremenljivka doseže vsak proces, ki uvaža nastavitve Django.
• Če uporabljate potek dela .env, preverite nalagalnik, namesto da predpostavljate, da Django datoteko bere samodejno.
• Obnovite stari produkcijski ključ, če je težava naključna izguba konfiguracije; zamenjajte ga le, kadar je to namenjeno ali zahtevano.
• Izvedite python manage.py check, za produkcijo pa izvedite check --deploy glede na produkcijski modul nastavitev.
• Po spremembi okolja znova zaženite dejansko storitev.

Ključna točka je, da ta izjema ne zahteva določenega čarobnega niza. Pove vam, da aktivne nastavitve Django ne vsebujejo uporabne skrivnosti. Popravite vir te konfiguracije, kadar je primerno ohranite namenjeni produkcijski ključ in preverite rezultat v istem okolju procesa, ki je prvotno odpovedalo.