Hvernig á að laga Django „ImproperlyConfigured: The SECRET_KEY Setting Must Not Be Empty“

Ef Django gefur villuna django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty er vandamálið einfalt: stillingamóðulið sem Django hlaðir inn gefur ekki upp nothæft SECRET_KEY gildi við keyrslu. Lagfærðu gildið í stillingamóðulinu sem er í raun notað, eða vertu viss um að umhverfisbreytan sem veitir það nái til Django ferlisins. Ekki leysa framleiðsluvandamál með því að setja varanlegan leyndarlykil inn í upprunastjórnunarkerfið.

Þessi leiðbeining var prófuð gegn Django 6.1 skjölunum. Django 6.1 var gefið út þann 5. ágúst 2026. Kjarnareglan er skýr: SECRET_KEY er sjálfgefið tómt strengur, verður að vera einstakt og óspáanlegt, og Django neitar að ræsa ef það er ekki stillt. Sjá opinbera Django SECRET_KEY stillingaviðmið.

Hvað þýðir „SECRET_KEY setting must not be empty“ í raun?

Það þýðir að þegar Django reyndi að nota settings.SECRET_KEY var leyst gildi tómt eða annars staðar fundið. Í nýju verkefni skrifar django-admin startproject venjulega framleiddan lykil inn í settings.py. Villan er því sérstaklega algeng eftir að verkefni hefur verið endurskipulagt fyrir mörg umhverfi, flutt í umhverfisbreytur, útfært á nýja þjónustu, eða ræst með öðru stillingamóðuli.

Fyrsta gagnlega spurningin er ekki „Hvernig finnst ég hvaða streng sem er til að fá netþjóninn til að ræsast?“ Heldur er hún „Hvaðan á þessi útfærsla að fá leyndarlykinn sinn?“ Þessi greinarmunur skiptir máli vegna þess að núverandi framleiðsluforrit ætti venjulega að endurheimta ætlaða leyndarlykinn sínum frekar en að búa sjálfkrafa til annan lykil í hverri ræsingu.

Algengar kóðamynstur sem valda villunni

SECRET_KEY = ""

# Vantar umhverfisbreyta skilar None
SECRET_KEY = os.getenv("SECRET_KEY")

# Vantar umhverfisbreyta fellur þöglu aftur á tóman streng
SECRET_KEY = os.getenv("SECRET_KEY", "")

Allar þrjár skilja Django eftir án nothæfs leyndarlykils þegar ytri gildið vantar. Fyrir framleiðslustillingar sýnir Django eigin útfærslueftirlitslisti fail-fast form:

import os

SECRET_KEY = os.environ["SECRET_KEY"]

Með þessu mynstri, vantar ferlis umhverfisbreyta, mistekst strax frekar en að verða þöglu að tómu gildi. Opinberi Django útfærslueftirlitslistinn segir einnig að framleiðslulykillinn ætti að vera stórt handahófskennt gildi, haldið leyndu, ekki endurnýtt annars staðar, og ekki sett inn í upprunastjórnunarkerfið.

Hvaða stillingaskrá er Django í raun að hlaða?

Áður en þú breytir skrá, staðfestu að það sé skráin sem skipunin þín eða forritsnetþjónninn notar. Django velur stillingamóðul í gegnum DJANGO_SETTINGS_MODULE, Python slóð eins og mysite.settings eða config.settings.production. Opinbera Django stillingaleiðbeiningin skjalfestir þessa virkni og --settings skipanalínustillinguna.

Til dæmis, að breyta config/settings.py mun ekki hjálpa ef þjónustan ræsir Django með:

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

Eins getur framleiðslu WSGI eða ASGI inngangspunktur stillt annað móðul. Athugaðu manage.py, wsgi.py, asgi.py, og raunverulega netþjónsskipun eða þjónustustillingar. Ef þú notar viljandi framleiðslustillingamóðul, prófaðu það sama móðul sérstaklega í stað þess að prófa þróunarskrá og gera ráð fyrir að niðurstaðan flytjist yfir.

Ættir þú að búa til nýjan SECRET_KEY eða endurheimta gamla?

Fyrir nýtt staðbundið verkefni: að búa til nýtt öruggt gildi er eðlilegt. Python staðlaða secrets móðulið er hannað fyrir dulkóðunarlega sterka handahófskenndni. Einn flytjanlegur skipun er:

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

Python skjölunin lýsir secrets sem móðulinu fyrir að búa til örugg handahófskennd gildi hentug fyrir lykilorð, auðkennismerki og tengda leyndarlykla. Sjá opinberu Python secrets skjölunina.

Fyrir núverandi framleiðsluforrit sem virkaði áður: reyndu fyrst að endurheimta sama ætlaða leyndarlykil frá leyndarkerfinu þínu eða útfærslustillingum. Django notar SECRET_KEY fyrir dulkóðunarundirritun og fyrir nokkra eiginleika, þar á meðal ákveðnar setu- og skilaboðastillingar og endurstillingarlykla fyrir lykilorð. Að skipta um lykil óvænt getur gert undirritað gögn ógild. Ef gamli lykillinn var ekki sýktur og truflunin er eingöngu umhverfisinnsetningavilla, þá forðast endurheimt hans yfirleitt óþarfa lyklaskipti.

Ef gamli lykillinn var lekur: skiptu um hann. Django 6.1 styður SECRET_KEY_FALLBACKS fyrir skipulögð lyklaskipti, sem leyfir gömlum lyklum að vera tekin við tímabundið á meðan ný undirritun notar nýja lykilinn. Fjarlægðu fallback lykla þegar umskiptatímabilinu er lokið. Hegðunin og kostnaðurinn er skjalfestur í opinberu SECRET_KEY_FALLBACKS viðmiðuninni.

Hvað er hraðasta örugga lagfæringin fyrir staðbundna þróun?

Ef þú ert aðeins að reyna að ræsa einnota staðbundnu verkefni, geturðu sett framleitt þróunargildi í virku stillingaskrána nógu lengi til að staðfesta greininguna:

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

Byrjaðu svo Django aftur. Ef villan hverfur, hefurðu staðfest að tóma stillingin var hindrunin. Ekki afrita framleiðsluleyndarlykil inn á þróunartölvu bara til að gera staðbundna uppsetningu þægilega, og ekki meðhöndla harðkóðað þróunargildi sem framleiðsluhönnun þína.

Er umhverfisbreytan í raun að ná til Django ferlisins?

Þetta er mikilvægasta athugunin þegar stillingaskráin þín inniheldur þegar SECRET_KEY = os.environ["SECRET_KEY"] eða jafngilda leit. Breytan verður að vera til staðar í umhverfi nákvæmlega þess ferlis sem flytur inn Django stillingar. Að stilla hana í einni terminal skilur hana ekki sjálfkrafa inni í núþegar keyrandi þjónustu, ílátum, ferlistjórnara, CI verkefni, eða sérstökum skel.

Prófaðu tilvist án þess að prenta leyndarlykilinn sjálfan:

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

Ef þetta prentar False, lagaðu umhverfisinnsetninguna fyrir það ferli. Fyrir fljótlega staðbundna skelprófun, notaðu setninguna fyrir skelina þína og ræstu svo Django frá sömu skel. Til dæmis:

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

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

Fyrir framleiðslu, notaðu leyndar/stillingakerfið sem veitt er af hýsingarplatforninni þinni eða ferlistjórnara frekar en að setja gildið í skipun sem gæti verið geymt í skelsögu.

Afhverju leysti það ekki Django að bæta SECRET_KEY við .env skrá?

Ein .env skrá er bara skrá þar til eitthvað hleður innihaldi hennar inn í ferlis umhverfið eða stillingakóðinn þinn lesur hana. Opinbert dæmi Django lesur os.environ; Django krefst ekki eða skjalfestir innbyggða sjálfvirka .env hleðslu. Ef verkefnið þitt treystir á dotenv bókasafn, rammaverkspakka, ílátastillingar, eða útfærslupall til að hlaða þeirri skrá, staðfestu þann hluta sérstaklega og staðfestu að hann keyri áður en settings.py lesur SECRET_KEY.

Gagnlegt aðgerð er að keyra boolean umhverfisathugunina hér að ofan frá sama íláti, þjónustureikningi, skel, eða keyrslustigi sem mistekst. Ef hún prentar False, mun villusöfnun á innihaldi settings.py einnar ekki laga ferlisstigs stillingavandamálið.

Hvað ef villan kemur fram aðeins í Docker, CI, collectstatic, WSGI, eða ASGI?

Það þýðir yfirleitt að annað ferli eða keyrslustig er að hlaða verkefninu með öðru umhverfi eða stillingamóðuli. Villan getur komið fram meðan á collectstatic, flutningum, prófunum, CI athugun, ræsingu forritsnetþjóns, eða bakgrunnsferli stendur, þótt runserver virki á fartölvunni þinni.

Ekki gera ráð fyrir að leyndarlykill sem er tiltækur við keyrslutíma sé einnig tiltækur meðan á myndbyggingu eða CI skrefi stendur. Öfugt, ekki gera ráð fyrir að breyta sem er flutt út í gagnvirka skel sé sýnileg kerfisþjónustu. Athugaðu þessi tvö atriði í mistekna samhenginu:

• Hvaða DJANGO_SETTINGS_MODULE eða --settings gildi er verið að nota?
• Hefur það nákvæma ferli ekki-tómt SECRET_KEY umhverfisbreyta áður en Django flytur inn stillingar?

Sérstaka leiðin til að setja inn leyndarlykil fer eftir Docker, CI veitanda þínum, hýsingaraðila, eða ferlistjórnara. Notaðu opinbera leyndarstjórnunarkerfi þess plattforms. Django-hliðar kröfan helst sú sama: valin stillingastilling verður að veita ekki-tóman leyndarlykil við keyrslutíma.

Hvernig staðfestir þú lagfæringuna án þess að leka lyklinum?

Fyrst, ekki prenta raunverulegan framleiðslulykil í logga bara til að sanna að hann sé til. Staðfestu tilvist með boolean athugun, leyfðu svo Django að hlaða stillingunum:

python manage.py check

Fyrir framleiðslustillingar, mælir Django með því að keyra útfærslueftirlitsathuganir gegn framleiðslustillingaskránni:

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

Skiptu um móðulsloðina með þinni raunverulegu framleiðslustillingamóðuli. Opinberi útfærslueftirlitslistinn mælir sérstaklega með check --deploy og varar við að það ætti að keyra gegn framleiðslustillingum.

Að lokum, endurræstu raunverulega forritsferlið. Breyta sem bætt er við eftir að þjónusta ræst hefur yfirleitt ekki áhrif á það núþegar keyrandi ferli. Ef endurræsta ferlið fer í gegnum athuganir Django og gefur ekki lengur undantekninguna, er stillingavandamálið leyst.

Hvaða lagfæringar ættir þú að forðast?

• Ekki stilla SECRET_KEY = "" eða nota tómt sjálfgefið. Það endurtekur aðstæðurnar sem Django hafnar.
• Ekki búa til nýjan lykil í hverri forritsræsingu. Breytilegur lykill getur gert undirritað gögn ógild og búið til ósamræmi milli margra vinnara.
• Ekki afrita leyndarlykil frá kennslu eða öðru verkefni. Django krefst einstaks, óspáanlegs gildis, og opinbert gildi eyðileggur tilgang leyndarlykils.
• Ekki setja framleiðslulykilinn inn í Git. Útfærslueftirlitslisti Django ráðleggur sérstaklega að halda honum utan upprunastjórnunar.
• Ekki prenta heila lykilinn í CI eða framleiðslu logga. Athugaðu aðeins hvort hann sé til staðar nema þú hafir stjórnað leyndarúttektarferli.
• Ekki gera ráð fyrir að .env skrá sé hlaðin eingöngu vegna þess að hún er til. Staðfestu hleðsluvirknina og raunverulega ferlis umhverfið.

Praktísk ákvörðunarleið

Lokaeftirlitslisti

• Staðfestu nákvæmlega hvaða stillingamóðul Django er að hlaða.
• Staðfestu að SECRET_KEY leysi í ekki-tómt gildi í því umhverfi.
• Notaðu einstakt, óspáanlegt gildi; ekki endurnýta opinberan eða kennslulykil.
• Haltu framleiðslulyklinum utan upprunastjórnunar.
• Ef þú notar umhverfisbreytur, vertu viss um að breytan nái til allra ferla sem flytja inn Django stillingar.
• Ef þú notar .env vinnufli, staðfestu hleðlarann frekar en að gera ráð fyrir að Django lesi skrána sjálfkrafa.
• Endurheimtu gamla framleiðslulykilinn ef vandamálið er óvilhöll stillingatap; skiptu um aðeins þegar ætlunin er eða krafist.
• Keyrðu python manage.py check, og fyrir framleiðslu keyrðu check --deploy gegn framleiðslustillingamóðulinu.
• Endurræstu raunverulegu þjónustuna eftir að hafa breytt umhverfi hennar.

Lykilatriðið er að þessi undantekning er ekki að biðja um ákveðinn töfrastreng. Hún er að segja þér að virku stillingar Django innihaldi ekki nothæfan leyndarlykil. Lagaðu uppruna þeirrar stillingar, varðveittu ætlaða framleiðslulykilinn þegar við á, og staðfestu niðurstöðuna í sama ferlis umhverfi og mistókst upphaflega.