文檔地址：https://github.com/openresty/lua-nginx-module

?

?

lua_package_path

syntax:?lua_package_path <lua-style-path-str>

default:?The content of LUA_PATH environment variable or Lua's compiled-in defaults.

context:?http

?

使用set_by_lua，?content_by_lua等指定的腳本來設置Lua module的搜索路徑。路徑字符串采用標準Lua路徑形式，;;?可用于表示原始搜索路徑。

從v0.5.0rc29發行版開始，特殊符號$prefix或${prefix}可用于搜索路徑字符串中，以指示在啟動Nginx服務器時server prefix，該路徑通常由-p PATH命令行選項確定的路徑。

?

lua_package_cpath

?

syntax:?lua_package_cpath <lua-style-cpath-str>

default:?The content of LUA_CPATH environment variable or Lua's compiled-in defaults.

context:?http

?

使用set_by_lua，?content_by_lua等指定的腳本設置Lua C-module的搜索路徑。cpath字符串采用標準的Lua cpath形式，;;?用來代表原始cpath。

從v0.5.0rc29發行版開始，特殊符號$prefix或${prefix}可用于搜索路徑字符串中，來指示server prefix在啟動Nginx服務器時通常由-p PATH命令行選項來確定該路徑。

?

?

init_by_lua_file

syntax:?init_by_lua_file <path-to-lua-script-file>

context:?http

phase:?loading-config

同?init_by_lua, except that the file specified by?<path-to-lua-script-file>?contains the Lua code or?Lua/LuaJIT bytecode?to be executed.

When a relative path like?foo/bar.lua?is given, they will be turned into the absolute path relative to the?server prefix?path determined by the?-p PATH?command-line option while starting the Nginx server.

This directive was first introduced in the?v0.5.5?release.

?

init_worker_by_lua

syntax:?init_worker_by_lua <lua-script-str>

context:?http

phase:?starting-worker

NOTE??v0.9.17?r版本后該指令不建議使用. 使用?init_worker_by_lua_block?指令來代替.

當master進程啟動時，在每個nginx worker進程啟動時運行指定的lua代碼。當master進程被禁用時，這個鉤子將在init_by_Lua*之后運行

此鉤子通常用于為每個worker創建計時器（通過ngx.timer.at lua api），用于后端健康檢查或其他定時例行工作。

?

?

content_by_lua_file

語法：?content_by_lua_file <path-to-lua-script-file>

上下文：?location, location if

階段：?content

等同于content_by_lua，不同之處在于指定的文件<path-to-lua-script-file>包含Lua代碼，或者從v0.5.0rc32發行版開始將執行Lua / LuaJIT?bytecode。

可以在<path-to-lua-script-file>字符串中使用Nginx變量來提供靈活性。然而，這存在一些風險，通常不推薦。

當給出一個相對路徑比如foo/bar.lua時，在啟動Nginx服務器時，它們將變成相對于由-p PATH命令行選項確定的server prefix路徑的絕對路徑。

當Lua代碼緩存打開時（默認情況下），用戶代碼將在第一次請求時加載一次并緩存，并且每次Lua源文件修改時都必須重新加載Nginx配置。可以在開發過程中臨時禁用Lua code cache，通過在nginx.conf中通過切換lua_code_cache?off，以避免重新加載Nginx。

在動態分派的文件路徑中支持Nginx變量，例如：

# CAUTION: contents in nginx var must be carefully filtered, # otherwise there'll be great security risk!location ~ ^/app/([-_a-zA-Z0-9/]+) {set $path $1;content_by_lua_file /path/to/lua/app/root/$path.lua;}

但要小心惡意用戶輸入，并且始終仔細驗證或過濾用戶提供的路徑組件。

?

lua_code_cache

?

語法:?lua_code_cache on | off

默認:?lua_code_cache on

上下文:?http, server, location, location if

?

在*_by_lua_file指令（如set_by_lua_file和?content_by_lua_file）和Lua模塊中為Lua代碼啟用或禁用Lua代碼緩存。

關閉時，ngx_lua提供的每個請求將從0.9.3發行版開始，在單獨的Lua VM實例中運行。因此，set_by_lua_file，content_by_lua_file，access_by_lua_file等中引用的Lua文件不會被緩存，所有使用的Lua模塊都將從頭開始加載。有了這個，開發人員可以采用編輯和刷新方法。

但請注意，當您在nginx.conf文件中編輯內聯Lua代碼時，在nginx.conf中內聯寫入的Lua代碼（如由set_by_lua，content_by_lua，?access_by_lua和rewrite_by_lua指定的代碼）將不會更新。因為只有Nginx配置文件解析器可以正確解析nginx.conf這個文件，所以唯一的方法是通過發送一個HUP信號或重新啟動Nginx 來重新加載配置文件，。

即使啟用代碼緩存，由dofile或者loadfile?裝載Lua的文件在* _by_lua_file不能被緩存（除非你自己緩存結果）。通常你可以使用init_by_lua?或者init_by_lua_file指令來加載所有這些文件，或者使這些Lua文件成為真正的Lua模塊并通過require加載它們。

ngx_lua模塊不支持stat模式，Apache?mod_lua模塊。

強烈建議禁用Lua代碼緩存以供生產使用，并且僅應在開發過程中使用，因為它會對整體性能產生重大負面影響。例如，禁用Lua代碼緩存后，“hello world”Lua示例的性能可能會下降一個數量級

?

lua_shared_dict

?

syntax:?lua_shared_dict <name> <size>

default:?no

context:?http

phase:?depends on usage

聲明一個共享內存區域，<name>作為存儲基于Lua詞典的ngx.shared.<name>的shm。

在當前的nginx server實例中，共享內存區域總是由所有nginx工作進程共享。

<size>參數接受諸如k和m的大小單位：

http { lua_shared_dict dogs 10m;...}

硬編的最小size為8KB，而實際的最小大小取決于實際的用戶數據設置（有些人以12KB開頭）。

有關詳細信息，請參閱ngx.shared.DICT。

該指令是在v0.3.1rc22版本中首次引入的。

?

content_by_lua

syntax:?content_by_lua <lua-script-str>

context:?location, location if

phase:?content

NOTE?不建議使用該指令在?v0.9.17?版本之后. 使用?content_by_lua_block?指令代替.

作為一個“內容處理程序”，and executes Lua code string specified in?<lua-script-str>?for every request. Lua代碼可以進行API調用，并在獨立的全局環境（即沙箱）中作為新的派生輔程序執行。(i.e. a sandbox).

不要在同一location中同時使用該指令和其他內容處理程序指令。例如，在同一個location中不能使用這個指令和proxy_pass?指令

?

content_by_lua_block

syntax:?content_by_lua_block { lua-script }

context:?location, location if

phase:?content

類似于content_by_lua指令，只是這個指令直接在一對花括號({})內聯Lua源，而不是在NGINX字符串文本(需要特殊字符轉義)中。

示例,

content_by_lua_block {ngx.say("I need no extra escaping here, for example: \r\nblah")}

該指令是在?v0.9.17?版本中首次引入的。

?

content_by_lua_file

syntax:?content_by_lua_file <path-to-lua-script-file>

context:?location, location if

phase:?content

相當于?content_by_lua, except that the file specified by?<path-to-lua-script-file>?contains the Lua code, or, as from the?v0.5.0rc32?release, the?Lua/LuaJIT bytecode?to be executed.

Nginx 變量可以在<path-to-lua-script-file>?格式的string中使用來提供靈活性 . 然而，這會帶來一些風險，通常不推薦。

當一個相對路徑比如?foo/bar.lua?is given,?在啟動Nginx服務器時，他們將轉換為絕對路徑根據由-p PATH命令行選項確定的服務器 prefix路徑

當Lua code cache 打開時?(默認為on), 在第一次請求時加載用戶代碼并緩存. 每次修改Lua源文件時都必須重新加載Nginx配置。The Lua code cache can be temporarily disabled during development by switching?lua_code_cache?off?in?nginx.conf?to avoid reloading Nginx.

在開發期間通過在nginx.conf中設置lua_code_cache off 來暫時禁用Lua代碼緩存，以避免重新加載Nginx，。

Nginx variables are supported in the file path for dynamic dispatch, for example:

# CAUTION: contents in nginx var must be carefully filtered,# otherwise there'll be great security risk!location ~ ^/app/([-_a-zA-Z0-9/]+) {set $path $1;content_by_lua_file /path/to/lua/app/root/$path.lua;}

But be very careful about malicious user inputs and always carefully validate or filter out the user-supplied path components.

?

操作系統api

os.execute ([command])

This function is equivalent to the C?function?system. It passes?command?to be executed by an operating system shell. It returns a status code, which is system-dependent. If?command?is absent, then it returns nonzero if a shell is available and zero otherwise.

這個函數相當于C函數?system, 它向操作系統shell傳遞要執行的command。它返回依賴系統的status狀態碼。如果command為空，那么返回非0，如果shell可用，那么可能返回0

?

?

Input and Output Facilities

io.popen (prog [, mode])

Starts program?prog?in a separated process and returns a file handle that you can use to read data from this program (if?mode?is?"r", the default) or to write data to this program (if?mode?is?"w").

This function is system dependent and is not available on all platforms.

開始程序prog于額外的進程,并返回用于prog的文件句柄(并不支持所有的系統平臺)

?

?

file:read(...)

　　功能：按指定的格式讀取一個文件,按每個格式函數將返回一個字串或數字,如果不能正確讀取將返回nil,若沒有指定格式將指默認按行方式進行讀取

　　格式：

　　"*n": 讀取一個數字

　　"*a": 從當前位置讀取整個文件,若為文件尾，則返回空字串

　　"*l": [默認]讀取下一行的內容,若為文件尾，則返回nil

　　number: 讀取指定字節數的字符,若為文件尾，則返回nil;如果number為0則返回空字串,若為文件尾，則返回nil;

?

?

Nginx API for Lua

ngx.hmac_sha1

syntax:?digest = ngx.hmac_sha1(secret_key, str)

Computes the?HMAC-SHA1?digest of the argument?str?and turns the result using the secret key?<secret_key>.

The raw binary form of the?HMAC-SHA1?digest will be generated, use?ngx.encode_base64, for example, to encode the result to a textual representation if desired.

?

ngx.timer.at

syntax:?hdl, err = ngx.timer.at(delay, callback, user_arg1, user_arg2, ...)

　創建一個帶有用戶回調函數的Nginx定時器以及可選的用戶參數。

第一個參數

　　delay指定定時器的延遲（以秒為單位）。可以指定小數秒0.001，這意味著1毫秒。0也可以指定延遲，在這種情況下，當當前處理程序產生執行時，定時器將立即過期。

第二個參數

　　callback可以是任何Lua函數，后面將在后面的“light thread”中調用延遲指定。用戶回調將自動Nginx的芯與參數調用premature， user_arg1，user_arg2，和等等，其中，所述premature 參數采用一個布爾值指示是否它是一個過早的計時器期滿或沒有，和user_arg1，user_arg2和等等，是那些（額外的）用戶調用ngx.timer.at 作為剩余參數時指定的參數。

　　當Nginx工作進程正在嘗試關閉時，會發生提前定時器到期，如在Nginx配置中由HUP信號觸發的重新加載或Nginx服務器關閉。當Nginx工作器試圖關閉時，不能再調用ngx.timer.at創建具有非零延遲的新定時器，在這種情況下ngx.timer.at將返回nil，還有一個描述錯誤的字符串，即“進程退出”。

　　從v0.9.3發行版開始，即使Nginx工作進程開始關閉，也允許創建零延遲定時器。

　　當定時器到期時，定時器回調中的用戶Lua代碼正在從創建定時器的原始請求完全分離的“輕線程”中運行。因此，與創建它們的請求（如子倉）具有相同生命周期的對象不能在原始請求和定時器用戶回調函數之間共享。

總結

以上是生活随笔為你收集整理的lua-nginx-module directives 中文版的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。